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