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 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.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.In net/ip6fw/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 /boot/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 HISTORY 545A 546.Nm 547utility 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 556API based upon code written by 557.An Daniel Boulet 558for BSDI. 559.Sh BUGS 560.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!! 561.Pp 562This program can put your computer in rather unusable state. 563When 564using it for the first time, work on the console of the computer, and 565do 566.Em NOT 567do anything you don't understand. 568.Pp 569When manipulating/adding chain entries, service and protocol names are 570not accepted. 571