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.5 2006/05/26 19:39:38 swildner 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 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 332.In net/ip6fw/ip6_fw.h ) 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 HISTORY 546A 547.Nm 548utility first appeared in 549.Fx 4.0 . 550.Sh AUTHORS 551.An Ugen J. S. Antsilevich , 552.An Poul-Henning Kamp , 553.An Alex Nash , 554.An Archie Cobbs . 555.Pp 556.An -nosplit 557API based upon code written by 558.An Daniel Boulet 559for BSDI. 560.Sh BUGS 561.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!! 562.Pp 563This program can put your computer in rather unusable state. 564When 565using it for the first time, work on the console of the computer, and 566do 567.Em NOT 568do anything you don't understand. 569.Pp 570When manipulating/adding chain entries, service and protocol names are 571not accepted. 572