contrib/ipfilter/man/ipfilter.4

   1 .\"     $FreeBSD$
   2 .\"
   3 .TH IP\ FILTER 4
   4 .SH NAME
   5 ipfilter \- Introduction to IP packet filtering
   6 .SH DESCRIPTION
   7 IP Filter is a TCP/IP packet filter, suitable for use in a firewall
   8 environment. To use, it can either be used as a loadable kernel module or
   9 incorporated into your UNIX kernel; use as a loadable kernel module where
  10 possible is highly recommended. Scripts are provided to install and patch
  11 system files, as required.
  12 .SH FEATURES
  13 The IP packet filter can:
  14 .IP
  15 explicitly deny/permit any packet from passing through
  16 .IP
  17 distinguish between various interfaces
  18 .IP
  19 filter by IP networks or hosts
  20 .IP
  21 selectively filter any IP protocol
  22 .IP
  23 selectively filter fragmented IP packets
  24 .IP
  25 selectively filter packets with IP options
  26 .IP
  27 send back an ICMP error/TCP reset for blocked packets
  28 .IP
  29 keep packet state information for TCP, UDP and ICMP packet flows
  30 .IP
  31 keep fragment state information for any IP packet, applying the same rule
  32 to all fragments.
  33 .IP
  34 act as a Network Address Translator (NAT)
  35 .IP
  36 use redirection to setup true transparent proxy connections
  37 .IP
  38 provide packet header details to a user program for authentication
  39 .IP
  40 in addition, supports temporary storage of pre-authenticated rules for passing packets through
  41 .PP
  42 Special provision is made for the three most common Internet protocols, TCP,
  43 UDP and ICMP. The IP Packet filter allows filtering of:
  44 .IP
  45 Inverted host/net matchingTCP/UDP packets by port number or a port number
  46 range
  47 .IP
  48 ICMP packets by type/code
  49 .IP
  50 "established" TCP packets
  51 .IP
  52 On any arbitrary combination of TCP flags
  53 .IP
  54 "short" (fragmented) IP packets with incomplete headers can be filtered
  55 .IP
  56 any of the 19 IP options or 8 registered IP security classes TOS (Type of
  57 Service) field in packets
  58 .PP
  59 To keep track of the performance of the IP packet filter, a logging device
  60 is used which supports logging of:
  61 .IP
  62 the TCP/UDP/ICMP and IP packet headers
  63 .IP
  64 the first 128 bytes of the packet (including headers)
  65 .PP
  66 A packet can be logged when:
  67 .IP
  68 it is successfully passed through
  69 .IP
  70 it is blocked from passing through
  71 .IP
  72 it matches a rule setup to look for suspicious packets
  73 .PP
  74 IP Filter keeps its own set of statistics on:
  75 .IP
  76 packets blocked
  77 .IP
  78 packets (and bytes!) used for accounting
  79 .IP
  80 packets passed
  81 .lP
  82 packets logged
  83 .IP
  84 attempts to log which failed (buffer full)
  85 .IP
  86 and much more, for packets going both in and out.
  87
  88 .SH Tools
  89 The current implementation provides a small set of tools, which can easily
  90 be used and integrated with regular unix shells and tools. A brief description
  91 of the tools provided:
  92 .PP
  93 ipf(8)
  94 reads in a set of rules, from either stdin or a file, and adds them to
  95 the kernels current list (appending them). It can also be used to flush the
  96 current filter set or delete individual filter rules. The file format is
  97 described in ipf(5).
  98 .PP
  99 ipfs(8)
 100 is a utility to temporarily lock the IP Filter kernel tables (state tables
 101 and NAT mappings) and write them to disk. After that the system can be
 102 rebooted, and ipfs can be used to read these tables from disk and restore
 103 them into the kernel. This way the system can be rebooted without the
 104 connections being terminated.
 105 .PP
 106 ipfstat(8)
 107 interrogates the kernel for statistics on packet filtering, so
 108 far, and retrieves the list of filters in operation for inbound and outbound
 109 packets.
 110 .PP
 111 ipftest(1)
 112 reads in a filter rule file and then applies sample IP packets to
 113 the rule file. This allows for testing of filter list and examination of how
 114 a packet is passed along through it.
 115 .PP
 116 ipmon(8)
 117 reads buffered data from the logging device (default is /dev/ipl)
 118 for output to either:
 119 .IP
 120 screen (standard output)
 121 .IP
 122 file
 123 .IP
 124 syslog
 125 .PP
 126 ipsend(1)
 127 generates arbitary IP packets for ethernet connected machines.
 128 .PP
 129 ipresend(1)
 130 reads in a data file of saved IP packets (ie
 131 snoop/tcpdump/etherfind output) and sends it back across the network.
 132 .PP
 133 iptest(1)
 134 contains a set of test "programs" which send out a series of IP
 135 packets, aimed at testing the strength of the TCP/IP stack at which it is
 136 aimed at. WARNING: this may crash machine(s) targeted!
 137 .PP
 138 ipnat(8)
 139 reads in a set of rules, from either stdin or a file and adds them
 140 to the kernels current list of active NAT rules. NAT rules can also be
 141 deleted using ipnat. The format of the configuration file to be used
 142 with ipnat is described in ipnat(5).
 143 .PP
 144 For use in your own programs (e.g. for writing of transparent application
 145 proxies), the programming interface and the associated ioctl's are
 146 documented in ipf(4).
 147
 148 Documentation on ioctl's and the format of data saved
 149 to the logging character device is provided in ipl(4)
 150 so that you may develop your own applications to work with or in place of any
 151 of the above.
 152
 153 Similar, the interface to the NAT code is documented in ipnat(4).
 154
 155 .SH PACKET PROCESSING FLOW
 156 The following diagram illustrates the flow of TCP/IP packets through the
 157 various stages introduced by IP Filter.
 158 .PP
 159 .nf
 160                                    IN
 161                                     |
 162                                     V
 163           +-------------------------+--------------------------+
 164           |                         |                          |
 165           |                         V                          |
 166           |            Network Address Translation             |
 167           |                         |                          |
 168           |         authenticated   |                          |
 169           |       +-------<---------+                          |
 170           |       |                 |                          |
 171           |       |                 V                          |
 172           |       V           IP Accounting                    |
 173           |       |                 |                          |
 174           |       |                 V                          |
 175           |       |        Fragment Cache Check--+             |
 176           |       |                 |            |             |
 177           |       V                 V            V             |
 178           |       |         Packet State Check-->+             |
 179           |       |                 |            |             |
 180           |       |       +->--+    |            |             |
 181           |       |       |    |    V            |             |
 182           |       V   groups   IP Filtering      V             |
 183           |       |       |    |    |            |             |
 184           |       |       +--<-+    |            |             |
 185           |       |                 |            |             |
 186           |       +---------------->|<-----------+             |
 187           |                         |                          |
 188           |                         V                          |
 189           |                +---<----+                          |
 190           |                |        |                          |
 191           |            function     |                          |
 192           |                |        V                          |
 193           |                +--->----+                          |
 194           |                         |                          |
 195           |                         V                          |
 196        +--|---<--- fast-route ---<--+                          |
 197        |  |                         |                          |
 198        |  |                         V                          |
 199        |  +-------------------------+--------------------------+
 200        |                            |
 201        |                        pass only
 202        |                            |
 203        |                            V
 204        V               [KERNEL TCP/IP Processing]
 205        |                            |
 206        |  +-------------------------+--------------------------+
 207        |  |                         |                          |
 208        |  |                         V                          |
 209        |  |                Fragment Cache Check--+             |
 210        |  |                         |            |             |
 211        |  |                         V            V             |
 212        |  |                 Packet State Check-->+             |
 213        |  |                         |            |             |
 214        |  |                         V            |             |
 215        V  |                    IP Filtering      |             |
 216        |  |                         |            V             |
 217        |  |                         |<-----------+             |
 218        |  |                         V                          |
 219        |  |                   IP Accounting                    |
 220        |  |                         |                          |
 221        |  |                         V                          |
 222        |  |            Network Address Translation             |
 223        |  |                         |                          |
 224        |  |                         V                          |
 225        |  +-------------------------+--------------------------+
 226        |                            |
 227        |                        pass only
 228        V                            |
 229        +--------------------------->|
 230                                     V
 231                                    OUT
 232 .fi
 233
 234 .SH MORE INFORMATION
 235 More information (including pointers to the FAQ and the mailing list) can be
 236 obtained from the sofware's official homepage: www.ipfilter.org
 237
 238 .SH SEE ALSO
 239 ipf(4), ipf(5), ipf(8), ipfilter(5), ipfs(8), ipfstat(8), ipftest(1),
 240 ipl(4), ipmon(8), ipnat(8), ipnat(4),
 241