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 . 571