sbin/ip6fw/ip6fw.8

   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
  52 flush
  53 .Nm
  54 .Op Fl q
  55 zero
  56 .Op Ar number ...
  57 .Nm
  58 delete
  59 .Ar number ...
  60 .Nm
  61 .Op Fl aftN
  62 list
  63 .Op Ar number ...
  64 .Nm
  65 .Op Fl ftN
  66 show
  67 .Op Ar number ...
  68 .Nm
  69 .Op Fl q
  70 add
  71 .Op Ar number
  72 .Ar action
  73 .Op log
  74 .Ar proto
  75 from
  76 .Ar src
  77 to
  78 .Ar dst
  79 .Op via Ar name | ipv6no
  80 .Op Ar options
  81 .Sh DESCRIPTION
  82 To ease configuration, rules can be put into a file which is
  83 processed using
  84 .Nm
  85 as shown in the first synopsis line.
  86 An absolute
  87 .Ar pathname
  88 must be used.
  89 The file
  90 will be read line by line and applied as arguments to the
  91 .Nm
  92 utility.
  93 .Pp
  94 Optionally, a preprocessor can be specified using
  95 .Fl p Ar preproc
  96 where
  97 .Ar pathname
  98 is to be piped through.
  99 Useful preprocessors include
 100 .Xr cpp 1
 101 and
 102 .Xr m4 1 .
 103 If
 104 .Ar preproc
 105 doesn't start with a slash
 106 .Pq Ql /
 107 as its first character, the usual
 108 .Ev PATH
 109 name search is performed.
 110 Care should be taken with this in environments where not all
 111 file systems are mounted (yet) by the time
 112 .Nm
 113 is being run (e.g. when they are mounted over NFS).
 114 Once
 115 .Fl p
 116 has been specified, optional
 117 .Fl D
 118 and
 119 .Fl U
 120 specifications can follow and will be passed on to the preprocessor.
 121 This allows for flexible configuration files (like conditionalizing
 122 them on the local hostname) and the use of macros to centralize
 123 frequently required arguments like IP addresses.
 124 .Pp
 125 The
 126 .Nm
 127 code works by going through the rule-list for each packet,
 128 until a match is found.
 129 All rules have two associated counters, a packet count and
 130 a byte count.
 131 These counters are updated when a packet matches the rule.
 132 .Pp
 133 The rules are ordered by a
 134 .Dq line-number
 135 from 1 to 65534 that is used
 136 to order and delete rules.
 137 Rules are tried in increasing order, and the
 138 first rule that matches a packet applies.
 139 Multiple rules may share the same number and apply in
 140 the order in which they were added.
 141 .Pp
 142 If a rule is added without a number, it is numbered 100 higher
 143 than the previous rule.
 144 If the highest defined rule number is
 145 greater than 65434, new rules are appended to the last rule.
 146 .Pp
 147 The delete operation deletes the first rule with number
 148 .Ar number ,
 149 if any.
 150 .Pp
 151 The list command prints out the current rule set.
 152 .Pp
 153 The show command is equivalent to `ip6fw -a list'.
 154 .Pp
 155 The zero operation zeroes the counters associated with rule number
 156 .Ar number .
 157 .Pp
 158 The flush operation removes all rules.
 159 .Pp
 160 Any command beginning with a
 161 .Sq # ,
 162 or being all blank, is ignored.
 163 .Pp
 164 One rule is always present:
 165 .Bd -literal -offset center
 166 65535 deny all from any to any
 167 .Ed
 168 .Pp
 169 This rule is the default policy, i.e., don't allow anything at all.
 170 Your job in setting up rules is to modify this policy to match your
 171 needs.
 172 .Pp
 173 The following options are available:
 174 .Bl -tag -width flag
 175 .It Fl a
 176 While listing, show counter values.  See also
 177 .Dq show
 178 command.
 179 .It Fl f
 180 Don't ask for confirmation for commands that can cause problems if misused
 181 (ie; flush).
 182 .Ar Note ,
 183 if there is no tty associated with the process, this is implied.
 184 .It Fl q
 185 While adding, zeroing or flushing, be quiet about actions (implies '-f').
 186 This is useful for adjusting rules by executing multiple ip6fw commands in a
 187 script (e.g. sh /etc/rc.firewall), or by processing a file of many ip6fw rules,
 188 across a remote login session.  If a flush is performed in normal
 189 (verbose) mode, it prints a message.  Because all rules are flushed, the
 190 message cannot be delivered to the login session, the login session is
 191 closed and the remainder of the ruleset is not processed.  Access to the
 192 console is required to recover.
 193 .It Fl t
 194 While listing, show last match timestamp.
 195 .It Fl N
 196 Try 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
 202 Allow packets that match rule.
 203 The search terminates.
 204 Aliases are
 205 .Ar pass ,
 206 .Ar permit ,
 207 and
 208 .Ar accept .
 209 .It Ar deny
 210 Discard packets that match this rule.
 211 The search terminates.
 212 .Ar Drop
 213 is an alias for
 214 .Ar deny .
 215 .It Ar reject
 216 (Deprecated.) Discard packets that match this rule, and try to send an ICMPv6
 217 host unreachable notice.
 218 The search terminates.
 219 .It Ar unreach code
 220 Discard packets that match this rule, and try to send an ICMPv6
 221 unreachable notice with code
 222 .Ar code ,
 223 where
 224 .Ar code
 225 is a number from zero to 255, or one of these aliases:
 226 .Ar noroute ,
 227 .Ar admin ,
 228 .Ar notneighbor ,
 229 .Ar addr ,
 230 or
 231 .Ar noport ,
 232 The search terminates.
 233 .It Ar reset
 234 TCP packets only.
 235 Discard packets that match this rule,
 236 and try to send a TCP reset (RST) notice.
 237 The search terminates
 238 .Em ( "not working yet" ) .
 239 .It Ar count
 240 Update counters for all packets that match rule.
 241 The search continues with the next rule.
 242 .It Ar skipto number
 243 Skip all subsequent rules numbered less than
 244 .Ar number .
 245 The search continues with the first rule numbered
 246 .Ar number
 247 or higher.
 248 .El
 249 .Pp
 250 If the kernel was compiled with
 251 .Dv IPV6FIREWALL_VERBOSE ,
 252 then when a packet matches a rule with the
 253 .Dq log
 254 keyword or a clear/resetlog is performed, a message will be logged to
 255 .Xr syslogd 8 ,
 256 or, if that fails, to the console.  If the kernel was compiled with the
 257 .Dv IPV6FIREWALL_VERBOSE_LIMIT
 258 option, then logging will cease after the number of packets
 259 specified by the option are received for that particular
 260 chain entry.
 261 When this limit is reached, the limit and rule number will be logged.
 262 Logging may then be re-enabled by clearing
 263 the packet counter for that entry.
 264 .Pp
 265 The
 266 .Xr syslogd 8
 267 logging and the default log limit are adjustable dynamically through the
 268 .Xr sysctl 8
 269 interface.
 270 .Pp
 271 .Ar proto :
 272 .Bl -hang -offset flag -width 16n
 273 .It Ar ipv6
 274 All packets match.
 275 The alias
 276 .Ar all
 277 has the same effect.
 278 .It Ar tcp
 279 Only TCP packets match.
 280 .It Ar udp
 281 Only UDP packets match.
 282 .It Ar ipv6-icmp
 283 Only ICMPv6 packets match.
 284 .It Ar <number|name>
 285 Only packets for the specified protocol matches (see
 286 .Pa /etc/protocols
 287 for a complete list).
 288 .El
 289 .Pp
 290 .Ar src
 291 and
 292 .Ar dst :
 293 .Bl -hang -offset flag
 294 .It Ar <address/prefixlen>
 295 .Op Ar ports
 296 .El
 297 .Pp
 298 The
 299 .Em <address/prefixlen>
 300 may be specified as:
 301 .Bl -hang -offset flag -width 16n
 302 .It Ar ipv6no
 303 An ipv6number of the form
 304 .Li fec0::1:2:3:4 .
 305 .It Ar ipv6no/prefixlen
 306 An ipv6number with a prefix length of the form
 307 .Li fec0::1:2:3:4/112 .
 308 .El
 309 .Pp
 310 The sense of the match can be inverted by preceding an address with the
 311 .Dq not
 312 modifier, causing all other addresses to be matched instead.
 313 This
 314 does not affect the selection of port numbers.
 315 .Pp
 316 With the TCP and UDP protocols, optional
 317 .Em ports
 318 may 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
 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 .Pa /usr/src/sys/netinet6/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 BUGS
 545 .Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
 546 .Pp
 547 This program can put your computer in rather unusable state.
 548 When
 549 using it for the first time, work on the console of the computer, and
 550 do
 551 .Em NOT
 552 do anything you don't understand.
 553 .Pp
 554 When manipulating/adding chain entries, service and protocol names are
 555 not 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
 563 API based upon code written by
 564 .An Daniel Boulet
 565 for BSDI.
 566 .Sh HISTORY
 567 A
 568 .Nm
 569 utility first appeared in
 570 .Fx 4.0 .