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