diff --git a/sbin/ipf/ipf/ipf.4 b/sbin/ipf/ipf/ipf.4 index c474d5d895de..c5b3bac34947 100644 --- a/sbin/ipf/ipf/ipf.4 +++ b/sbin/ipf/ipf/ipf.4 @@ -1,253 +1,252 @@ .TH IPF 4 .SH NAME ipf \- packet filtering kernel interface .SH SYNOPSIS #include .br #include .SH IOCTLS -.PP To add and delete rules to the filter list, three 'basic' ioctls are provided for use. The ioctl's are called as: .LP .nf ioctl(fd, SIOCADDFR, struct frentry **) ioctl(fd, SIOCDELFR, struct frentry **) ioctl(fd, SIOCIPFFL, int *) .fi .PP However, the full complement is as follows: .LP .nf ioctl(fd, SIOCADAFR, struct frentry **) (same as SIOCADDFR) ioctl(fd, SIOCRMAFR, struct frentry **) (same as SIOCDELFR) ioctl(fd, SIOCADIFR, struct frentry **) ioctl(fd, SIOCRMIFR, struct frentry **) ioctl(fd, SIOCINAFR, struct frentry **) ioctl(fd, SIOCINIFR, struct frentry **) ioctl(fd, SIOCSETFF, u_int *) ioctl(fd, SIOGGETFF, u_int *) ioctl(fd, SIOCGETFS, struct friostat **) ioctl(fd, SIOCIPFFL, int *) ioctl(fd, SIOCIPFFB, int *) ioctl(fd, SIOCSWAPA, u_int *) ioctl(fd, SIOCFRENB, u_int *) ioctl(fd, SIOCFRSYN, u_int *) ioctl(fd, SIOCFRZST, struct friostat **) ioctl(fd, SIOCZRLST, struct frentry **) ioctl(fd, SIOCAUTHW, struct fr_info **) ioctl(fd, SIOCAUTHR, struct fr_info **) ioctl(fd, SIOCATHST, struct fr_authstat **) .fi .PP The variations, SIOCADAFR vs. SIOCADIFR, allow operation on the two lists, active and inactive, respectively. All of these ioctl's are implemented as being routing ioctls and thus the same rules for the various routing ioctls and the file descriptor are employed, mainly being that the fd must be that of the device associated with the module (i.e., /dev/ipl). .PP The three groups of ioctls above perform adding rules to the end of the list (SIOCAD*), deletion of rules from any place in the list (SIOCRM*) and insertion of a rule into the list (SIOCIN*). The rule place into which it is inserted is stored in the "fr_hits" field, below. .LP .nf typedef struct frentry { struct frentry *fr_next; u_short fr_group; /* group to which this rule belongs */ u_short fr_grhead; /* group # which this rule starts */ struct frentry *fr_grp; int fr_ref; /* reference count - for grouping */ void *fr_ifa; #ifdef BSD void *fr_oifa; #endif /* * These are only incremented when a packet matches this rule and * it is the last match */ U_QUAD_T fr_hits; U_QUAD_T fr_bytes; /* * Fields after this may not change whilst in the kernel. */ struct fr_ip fr_ip; struct fr_ip fr_mip; /* mask structure */ u_char fr_tcpfm; /* tcp flags mask */ u_char fr_tcpf; /* tcp flags */ u_short fr_icmpm; /* data for ICMP packets (mask) */ u_short fr_icmp; u_char fr_scmp; /* data for port comparisons */ u_char fr_dcmp; u_short fr_dport; u_short fr_sport; u_short fr_stop; /* top port for <> and >< */ u_short fr_dtop; /* top port for <> and >< */ u_32_t fr_flags; /* per-rule flags && options (see below) */ u_short fr_skip; /* # of rules to skip */ u_short fr_loglevel; /* syslog log facility + priority */ int (*fr_func)(int, ip_t *, fr_info_t *)); char fr_icode; /* return ICMP code */ char fr_ifname[IFNAMSIZ]; #ifdef BSD char fr_oifname[IFNAMSIZ]; #endif struct frdest fr_tif; /* "to" interface */ struct frdest fr_dif; /* duplicate packet interfaces */ } frentry_t; .fi .PP When adding a new rule, all unused fields (in the filter rule) should be initialised to be zero. To insert a rule, at a particular position in the filter list, the number of the rule which it is to be inserted before must be put in the "fr_hits" field (the first rule is number 0). .PP Flags which are recognised in fr_flags: .nf FR_BLOCK 0x000001 /* do not allow packet to pass */ FR_PASS 0x000002 /* allow packet to pass */ FR_OUTQUE 0x000004 /* outgoing packets */ FR_INQUE 0x000008 /* ingoing packets */ FR_LOG 0x000010 /* Log */ FR_LOGB 0x000011 /* Log-fail */ FR_LOGP 0x000012 /* Log-pass */ FR_LOGBODY 0x000020 /* log the body of packets too */ FR_LOGFIRST 0x000040 /* log only the first packet to match */ FR_RETRST 0x000080 /* return a TCP RST packet if blocked */ FR_RETICMP 0x000100 /* return an ICMP packet if blocked */ FR_FAKEICMP 0x00180 /* Return ICMP unreachable with fake source */ FR_NOMATCH 0x000200 /* no match occurred */ FR_ACCOUNT 0x000400 /* count packet bytes */ FR_KEEPFRAG 0x000800 /* keep fragment information */ FR_KEEPSTATE 0x001000 /* keep `connection' state information */ FR_INACTIVE 0x002000 FR_QUICK 0x004000 /* match & stop processing list */ FR_FASTROUTE 0x008000 /* bypass normal routing */ FR_CALLNOW 0x010000 /* call another function (fr_func) if matches */ FR_DUP 0x020000 /* duplicate the packet */ FR_LOGORBLOCK 0x040000 /* block the packet if it can't be logged */ FR_NOTSRCIP 0x080000 /* not the src IP# */ FR_NOTDSTIP 0x100000 /* not the dst IP# */ FR_AUTH 0x200000 /* use authentication */ FR_PREAUTH 0x400000 /* require preauthentication */ .fi .PP Values for fr_scomp and fr_dcomp (source and destination port value comparisons) : .LP .nf FR_NONE 0 FR_EQUAL 1 FR_NEQUAL 2 FR_LESST 3 FR_GREATERT 4 FR_LESSTE 5 FR_GREATERTE 6 FR_OUTRANGE 7 FR_INRANGE 8 .fi .PP The third ioctl, SIOCIPFFL, flushes either the input filter list, the output filter list or both and it returns the number of filters removed from the list(s). The values which it will take and recognise are FR_INQUE and FR_OUTQUE (see above). This ioctl is also implemented for \fB/dev/ipstate\fP and will flush all state tables entries if passed 0 or just all those which are not established if passed 1. .IP "\fBGeneral Logging Flags\fP" 0 There are two flags which can be set to log packets independently of the rules used. These allow for packets which are either passed or blocked to be logged. To set (and clear)/get these flags, two ioctls are provided: .IP SIOCSETFF 16 Takes an unsigned integer as the parameter. The flags are then set to those provided (clearing/setting all in one). .nf FF_LOGPASS 0x10000000 FF_LOGBLOCK 0x20000000 FF_LOGNOMATCH 0x40000000 FF_BLOCKNONIP 0x80000000 /* Solaris 2.x only */ .fi .IP SIOCGETFF 16 Takes a pointer to an unsigned integer as the parameter. A copy of the flags currently in used is copied to user space. .IP "\fBFilter statistics\fP" 0 Statistics on the various operations performed by this package on packets is kept inside the kernel. These statistics apply to packets traversing through the kernel. To retrieve this structure, use this ioctl: .nf ioctl(fd, SIOCGETFS, struct friostat *) struct friostat { struct filterstats f_st[2]; struct frentry *f_fin[2]; struct frentry *f_fout[2]; struct frentry *f_acctin[2]; struct frentry *f_acctout[2]; struct frentry *f_auth; u_long f_froute[2]; int f_active; /* 1 or 0 - active rule set */ int f_defpass; /* default pass - from fr_pass */ int f_running; /* 1 if running, else 0 */ int f_logging; /* 1 if enabled, else 0 */ char f_version[32]; /* version string */ }; struct filterstats { u_long fr_pass; /* packets allowed */ u_long fr_block; /* packets denied */ u_long fr_nom; /* packets which don't match any rule */ u_long fr_ppkl; /* packets allowed and logged */ u_long fr_bpkl; /* packets denied and logged */ u_long fr_npkl; /* packets unmatched and logged */ u_long fr_pkl; /* packets logged */ u_long fr_skip; /* packets to be logged but buffer full */ u_long fr_ret; /* packets for which a return is sent */ u_long fr_acct; /* packets for which counting was performed */ u_long fr_bnfr; /* bad attempts to allocate fragment state */ u_long fr_nfr; /* new fragment state kept */ u_long fr_cfr; /* add new fragment state but complete pkt */ u_long fr_bads; /* bad attempts to allocate packet state */ u_long fr_ads; /* new packet state kept */ u_long fr_chit; /* cached hit */ u_long fr_pull[2]; /* good and bad pullup attempts */ #if SOLARIS u_long fr_notdata; /* PROTO/PCPROTO that have no data */ u_long fr_nodata; /* mblks that have no data */ u_long fr_bad; /* bad IP packets to the filter */ u_long fr_notip; /* packets passed through no on ip queue */ u_long fr_drop; /* packets dropped - no info for them! */ #endif }; .fi If we wanted to retrieve all the statistics and reset the counters back to 0, then the ioctl() call would be made to SIOCFRZST rather than SIOCGETFS. In addition to the statistics above, each rule keeps a hit count, counting both number of packets and bytes. To reset these counters for a rule, load the various rule information into a frentry structure and call SIOCZRLST. .IP "Swapping Active lists" 0 IP Filter supports two lists of rules for filtering and accounting: an active list and an inactive list. This allows for large scale rule base changes to be put in place atomically with otherwise minimal interruption. Which of the two is active can be changed using the SIOCSWAPA ioctl. It is important to note that no passed argument is recognised and that the value returned is that of the list which is now inactive. .br .SH FILES /dev/ipauth .br /dev/ipl .br /dev/ipnat .br /dev/ipstate .SH SEE ALSO ipl(4), ipnat(4), ipf(5), ipf(8), ipfstat(8) diff --git a/sbin/ipf/ipf/ipf.5 b/sbin/ipf/ipf/ipf.5 index 423e0de1b34e..32e9913353a0 100644 --- a/sbin/ipf/ipf/ipf.5 +++ b/sbin/ipf/ipf/ipf.5 @@ -1,1697 +1,1660 @@ .TH IPF 5 .SH NAME ipf, ipf.conf \- IPFilter firewall rules file format .SH DESCRIPTION -.PP The ipf.conf file is used to specify rules for the firewall, packet authentication and packet accounting components of IPFilter. To load rules specified in the ipf.conf file, the ipf(8) program is used. .PP For use as a firewall, there are two important rule types: those that block and drop packets (block rules) and those that allow packets through (pass rules.) Accompanying the decision to apply is a collection of statements that specify under what conditions the result is to be applied and how. .PP The simplest rules that can be used in ipf.conf are expressed like this: .PP .nf block in all pass out all .fi .PP Each rule must contain at least the following three components .RS .IP * a decision keyword (pass, block, etc.) .IP * the direction of the packet (in or out) .IP * address patterns or "all" to match any address information .RE .SS Long lines -.PP For rules lines that are particularly long, it is possible to split them over multiple lines implicitly like this: .PP .nf pass in on bgeo proto tcp from 1.1.1.1 port > 1000 to 2.2.2.2 port < 5000 flags S keep state .fi .PP or explicitly using the backslash ('\\') character: .PP .nf pass in on bgeo proto tcp from 1.1.1.1 port > 1000 \\ to 2.2.2.2 port < 5000 flags S keep state .fi .SS Comments -.PP Comments in the ipf.conf file are indicated by the use of the '#' character. This can either be at the start of the line, like this: .PP .nf # Allow all ICMP packets in pass in proto icmp from any to any .fi .PP Or at the end of a like, like this: .PP .nf pass in proto icmp from any to any # Allow all ICMP packets in .fi .SH Firewall rules -.PP This section goes into detail on how to construct firewall rules that are placed in the ipf.conf file. .PP It is beyond the scope of this document to describe what makes a good firewall rule set or which packets should be blocked or allowed in. Some suggestions will be provided but further reading is expected to fully understand what is safe and unsafe to allow in/out. .SS Filter rule keywords -.PP The first word found in any filter rule describes what the eventual outcome of a packet that matches it will be. Descriptions of the many and various sections that can be used to match on the contents of packet headers will follow on below. .PP The complete list of keywords, along with what they do is as follows: .RS .HP pass rules that match a packet indicate to ipfilter that it should be allowed to continue on in the direction it is flowing. .HP block rules are used when it is desirable to prevent a packet from going any further. Packets that are blocked on the "in" side are never seen by TCP/IP and those that are blocked going "out" are never seen on the wire. .HP log when IPFilter successfully matches a packet against a log rule a log record is generated and made available for ipmon(8) to read. These rules have no impact on whether or not a packet is allowed through or not. So if a packet first matched a block rule and then matched a log rule, the status of the packet after the log rule is that it will still be blocked. .HP count rules provide the administrator with the ability to count packets and bytes that match the criteria laid out in the configuration file. The count rules are applied after NAT and filter rules on the inbound path. For outbound packets, count rules are applied before NAT and before the packet is dropped. Thus the count rule cannot be used as a true indicator of link layer .HP auth rules cause the matching packet to be queued up for processing by a user space program. The user space program is responsible for making an ioctl system call to collect the information about the queued packet and another ioctl system call to return the verdict (block, pass, etc) on what to do with the packet. In the event that the queue becomes full, the packets will end up being dropped. .HP call provides access to functions built into IPFilter that allow for more complex actions to be taken as part of the decision making that goes with the rule. .HP decapsulate rules instruct ipfilter to remove any other headers (IP, UDP, AH) and then process what is inside as a new packet. For non-UDP packets, there are builtin checks that are applied in addition to whatever is specified in the rule, to only allow decapsulation of recognised protocols. After decapsulating the inner packet, any filtering result that is applied to the inner packet is also applied to the other packet. .PP The default way in which filter rules are applied is for the last matching rule to be used as the decision maker. So even if the first rule to match a packet is a pass, if there is a later matching rule that is a block and no further rules match the packet, then it will be blocked. .SS Matching Network Interfaces -.PP On systems with more than one network interface, it is necessary to be able to specify different filter rules for each of them. In the first instance, this is because different networks will send us packets via each network interface but it is also because of the hosts, the role and the resulting security policy that we need to be able to distinguish which network interface a packet is on. .PP To accommodate systems where the presence of a network interface is dynamic, it is not necessary for the network interface named in a filter rule to be present in the system when the rule is loaded. This can lead to silent errors being introduced and unexpected behaviour with the simplest of keyboard mistakes - for example, typing in hem0 instead of hme0 or hme2 instead of hme3. .PP On Solaris systems prior to Solaris 10 Update 4, it is not possible to filter packets on the loopback interface (lo0) so filter rules that specify it will have no impact on the corresponding flow of packets. See below for Solaris specific tips on how to enable this. .PP Some examples of including the network interface in filter rules are: .PP .nf block in on bge0 all pass out on bge0 all .fi .SS Address matching (basic) -.PP The first and most basic part of matching for filtering rules is to specify IP addresses and TCP/UDP port numbers. The source address information is matched by the "from" information in a filter rule and the destination address information is matched with the "to" information in a filter rule. .PP The typical format used for IP addresses is CIDR notation, where an IP address (or network) is followed by a '/' and a number representing the size of the netmask in bits. This notation is used for specifying address matching in both IPv4 and IPv6. If the '/' and bitmask size are excluded from the matching string, it is assumed that the address specified is a host address and that the netmask applied should be all 1's. .PP Some examples of this are: .PP .nf pass in from 10.1.0.0/24 to any block out from any to 10.1.1.1 .fi .PP It is not possible to specify a range of addresses that does not have a boundary that can be defined by a standard subnet mask. .IP .B Names instead of addresses .RS .PP Hostnames, resolved either via DNS or /etc/hosts, or network names, resolved via /etc/networks, may be used in place of actual addresses in the filter rules. WARNING: if a hostname expands to more than one address, only the *first* is used in building the filter rule. .PP Caution should be exercised when relying on DNS for filter rules in case the sending and receiving of DNS packets is blocked when ipf(8) is processing that part of the configuration file, leading to long delays, if not errors, in loading the filter rules. .RE .SS Protocol Matching -.PP To match packets based on TCP/UDP port information, it is first necessary to indicate which protocol the packet must be. This is done using the "proto" keyword, followed by either the protocol number or a name which is mapped to the protocol number, usually through the /etc/protocols file. .PP .nf pass in proto tcp from 10.1.0.0/24 to any block out proto udp from any to 10.1.1.1 pass in proto icmp from any to 192.168.0.0/16 .fi .SS Sending back error packets -.PP When a packet is just discarded using a block rule, there is no feedback given to the host that sent the packet. This is both good and bad. If this is the desired behaviour and it is not desirable to send any feedback about packets that are to be denied. The catch is that often a host trying to connect to a TCP port or with a UDP based application will send more than one packet because it assumes that just one packet may be discarded so a retry is required. The end result being logs can become cluttered with duplicate entries due to the retries. .PP To address this problem, a block rule can be qualified in two ways. The first of these is specific to TCP and instructs IPFilter to send back a reset (RST) packet. This packet indicates to the remote system that the packet it sent has been rejected and that it shouldn't make any further attempts to send packets to that port. Telling IPFilter to return a TCP RST packet in response to something that has been received is achieved with the return-rst keyword like this: .PP .nf block return-rst in proto tcp from 10.0.0.0/8 to any .fi .PP When sending back a TCP RST packet, IPFilter must construct a new packet that has the source address of the intended target, not the source address of the system it is running on (if they are different.) .PP For all of the other protocols handled by the IP protocol suite, to send back an error indicating that the received packet was dropped requires sending back an ICMP error packet. Whilst these can also be used for TCP, the sending host may not treat the received ICMP error as a hard error in the same way as it does the TCP RST packet. To return an ICMP error it is necessary to place return-icmp after the block keyword like this: .PP .nf block return-icmp in proto udp from any to 192.168.0.1/24 .fi .PP When electing to return an ICMP error packet, it is also possible to select what type of ICMP error is returned. Whilst the full compliment of ICMP unreachable codes can be used by specifying a number instead of the string below, only the following should be used in conjunction with return-icmp. Which return code to use is a choice to be made when weighing up the pro's and con's. Using some of the codes may make it more obvious that a firewall is being used rather than just the host not responding. .RS .HP filter-prohib (prohibited by filter) sending packets to the destination given in the received packet is prohibited due to the application of a packet filter .HP net-prohib (prohibited network) sending packets to the destination given in the received packet is administratively prohibited. .HP host-unk (host unknown) the destination host address is not known by the system receiving the packet and therefore cannot be reached. .HP host-unr (host unreachable) it is not possible to reach the host as given by the destination address in the packet header. .HP net-unk (network unknown) the destination network address is not known by the system receiving the packet and therefore cannot be reached. .HP net-unr (network unreachable) it is not possible to forward the packet on to its final destination as given by the destination address .HP port-unr (port unreachable) there is no application using the given destination port and therefore it is not possible to reach that port. .HP proto-unr (protocol unreachable) the IP protocol specified in the packet is not available to receive packets. .RE .PP An example that shows how to send back a port unreachable packet for UDP packets to 192.168.1.0/24 is as follows: .PP .nf block return-icmp(port-unr) in proto udp from any to 192.168.1.0/24 .fi .PP In the above examples, when sending the ICMP packet, IPFilter will construct a new ICMP packet with a source address of the network interface used to send the packet back to the original source. This can give away that there is an intermediate system blocking packets. To have IPFilter send back ICMP packets where the source address is the original destination, regardless of whether or not it is on the local host, return-icmp-as-dest is used like this: .PP .nf block return-icmp-as-dest(port-unr) in proto udp \\ from any to 192.168.1.0/24 .fi .SS TCP/UDP Port Matching -.PP Having specified which protocol is being matched, it is then possible to indicate which port numbers a packet must have in order to match the rule. Due to port numbers being used differently to addresses, it is therefore possible to match on them in different ways. IPFilter allows you to use the following logical operations: .IP "< x" is true if the port number is greater than or equal to x and less than or equal to y is true if the port number in the packet is less than x .IP "<= x" is true if the port number in the packet is less than or equal to x .IP "> x" is true if the port number in the packet is greater than x .IP ">= x" is true if the port number in the packet is greater or equal to x .IP "= x" is true if the port number in the packet is equal to x .IP "!= x" is true if the port number in the packet is not equal to x .PP Additionally, there are a number of ways to specify a range of ports: .IP "x <> y" is true if the port number is less than a and greater than y .IP "x >< y" is true if the port number is greater than x and less than y .IP "x:y" is true if the port number is greater than or equal to x and less than or equal to y .PP Some examples of this are: .PP .nf block in proto tcp from any port >= 1024 to any port < 1024 pass in proto tcp from 10.1.0.0/24 to any port = 22 block out proto udp from any to 10.1.1.1 port = 135 pass in proto udp from 1.1.1.1 port = 123 to 10.1.1.1 port = 123 pass in proto tcp from 127.0.0.0/8 to any port 6000:6009 .fi .PP If there is no desire to mention any specific source or destintion information in a filter rule then the word "all" can be used to indicate that all addresses are considered to match the rule. .SS IPv4 or IPv6 -.PP If a filter rule is constructed without any addresses then IPFilter will attempt to match both IPv4 and IPv6 packets with it. In the next list of rules, each one can be applied to either network protocol because there is no address specified from which IPFilter can derive with network protocol to expect. .PP .nf pass in proto udp from any to any port = 53 block in proto tcp from any port < 1024 to any .fi .PP To explicitly match a particular network address family with a specific rule, the family must be added to the rule. For IPv4 it is necessary to add family inet and for IPv6, family inet6. Thus the next rule will block all packets (both IPv4 and IPv6: .PP .nf block in all .fi .PP but in the following example, we block all IPv4 packets and only allow in IPv6 packets: .PP .nf block in family inet all pass in family inet6 all .fi .PP To continue on from the example where we allowed either IPv4 or IPv6 packets to port 53 in, to change that such that only IPv6 packets to port 53 need to allowed blocked then it is possible to add in a protocol family qualifier: .PP .nf pass in family inet6 proto udp from any to any port = 53 .fi .SS First match vs last match -.PP To change the default behaviour from being the last matched rule decides the outcome to being the first matched rule, the word "quick" is inserted to the rule. .SH Extended Packet Matching .SS Beyond using plain addresses -.PP On firewalls that are working with large numbers of hosts and networks or simply trying to filter discretely against various hosts, it can be an easier administration task to define a pool of addresses and have a filter rule reference that address pool rather than have a rule for each address. .PP In addition to being able to use address pools, it is possible to use the interface name(s) in the from/to address fields of a rule. If the name being used in the address section can be matched to any of the interface names mentioned in the rule's "on" or "via" fields then it can be used with one of the following keywords for extended effect: .HP broadcast use the primary broadcast address of the network interface for matching packets with this filter rule; .IP .nf pass in on fxp0 proto udp from any to fxp0/broadcast port = 123 .fi .HP peer use the peer address on point to point network interfaces for matching packets with this filter rule. This option typically only has meaningful use with link protocols such as SLIP and PPP. For example, this rule allows ICMP packets from the remote peer of ppp0 to be received if they're destined for the address assigned to the link at the firewall end. .IP .nf pass in on ppp0 proto icmp from ppp0/peer to ppp0/32 .fi .HP netmasked use the primary network address, with its netmask, of the network interface for matching packets with this filter rule. If a network interface had an IP address of 192.168.1.1 and its netmask was 255.255.255.0 (/24), then using the word "netmasked" after the interface name would match any addresses that would match 192.168.1.0/24. If we assume that bge0 has this IP address and netmask then the following two rules both serve to produce the same effect: .IP .nf pass in on bge0 proto icmp from any to 192.168.1.0/24 pass in on bge0 proto icmp from any to bge0/netmasked .fi .HP network using the primary network address, and its netmask, of the network interface, construct an address for exact matching. If a network interface has an address of 192.168.1.1 and its netmask is 255.255.255.0, using this option would only match packets to 192.168.1.0. .IP .nf pass in on bge0 proto icmp from any to bge0/network .fi .PP Another way to use the name of a network interface to get the address is to wrap the name in ()'s. In the above method, IPFilter looks at the interface names in use and to decide whether or not the name given is a hostname or network interface name. With the use of ()'s, it is possible to tell IPFilter that the name should be treated as a network interface name even though it doesn't appear in the list of network interface that the rule ias associated with. .IP .nf pass in proto icmp from any to (bge0)/32 .fi .SS Using address pools -.PP Rather than list out multiple rules that either allow or deny specific addresses, it is possible to create a single object, call an address pool, that contains all of those addresses and reference that in the filter rule. For documentation on how to write the configuration file for those pools and load them, see ippool.conf(5) and ippool(8). There are two types of address pools that can be defined in ippool.conf(5): trees and hash tables. To refer to a tree defined in ippool.conf(5), use this syntax: .PP .nf pass in from pool/trusted to any .fi .PP Either a name or number can be used after the '/', just so long as it matches up with something that has already been defined in ipool.conf(5) and loaded in with ippool(8). Loading a filter rule that references a pool that does not exist will result in an error. .PP If hash tables have been used in ippool.conf(5) to store the addresses in instead of a tree, then replace the word pool with hash: .IP .nf pass in from any to hash/webservers .fi .PP There are different operational characteristics with each, so there may be some situations where a pool works better than hash and vice versa. .SS Matching TCP flags -.PP The TCP header contains a field of flags that is used to decide if the packet is a connection request, connection termination, data, etc. By matching on the flags in conjunction with port numbers, it is possible to restrict the way in which IPFilter allows connections to be created. A quick overview of the TCP flags is below. Each is listed with the letter used in IPFilter rules, followed by its three or four letter pneumonic. .HP S SYN - this bit is set when a host is setting up a connection. The initiator typically sends a packet with the SYN bit and the responder sends back SYN plus ACK. .HP A ACK - this bit is set when the sender wishes to acknowledge the receipt of a packet from another host .HP P PUSH - this bit is set when a sending host has send some data that is yet to be acknowledged and a reply is sought .HP F FIN - this bit is set when one end of a connection starts to close the connection down .HP U URG - this bit is set to indicate that the packet contains urgent data .HP R RST - this bit is set only in packets that are a reply to another that has been received but is not targeted at any open port .HP C CWN .HP E ECN .PP When matching TCP flags, it is normal to just list the flag that you wish to be set. By default the set of flags it is compared against is "FSRPAU". Rules that say "flags S" will be displayed by ipfstat(8) as having "flags S/FSRPAU". This is normal. The last two flags, "C" and "E", are optional - they may or may not be used by an end host and have no bearing on either the acceptance of data nor control of the connection. Masking them out with "flags S/FSRPAUCE" may cause problems for remote hosts making a successful connection. .PP .nf pass in quick proto tcp from any to any port = 22 flags S/SAFR pass out quick proto tcp from any port = 22 to any flags SA .fi .PP By itself, filtering based on the TCP flags becomes more work but when combined with stateful filtering (see below), the situation changes. .SS Matching on ICMP header information -.PP The TCP and UDP are not the only protocols for which filtering beyond just the IP header is possible, extended matching on ICMP packets is also available. The list of valid ICMP types is different for IPv4 vs IPv6. .PP As a practical example, to allow the ping command to work against a specific target requires allowing two different types of ICMP packets, like this: .PP .nf pass in proto icmp from any to webserver icmp-type echo pass out proto icmp from webserver to any icmp-type echorep .fi .PP The ICMP header has two fields that are of interest for filtering: the ICMP type and code. Filter rules can accept either a name or number for both the type and code. The list of names supported for ICMP types is listed below, however only ICMP unreachable errors have named codes (see above.) .PP The list of ICMP types that are available for matching an IPv4 packet are as follows: .PP echo (echo request), echorep (echo reply), inforeq (information request), inforep (information reply), maskreq (mask request), maskrep (mask reply), paramprob (parameter problem), redir (redirect), routerad (router advertisement), routersol (router solicit), squence (source quence), timest (timestamp), timestreq (timestamp reply), timex (time exceeded), unreach (unreachable). .PP The list of ICMP types that are available for matching an IPv6 packet are as follows: .PP echo (echo request), echorep (echo reply), fqdnquery (FQDN query), fqdnreply (FQDN reply), inforeq (information request), inforep (information reply), listendone (MLD listener done), listendqry (MLD listener query), listendrep (MLD listener reply), neighadvert (neighbour advert), neighborsol (neighbour solicit), paramprob (parameter problem), redir (redirect), renumber (router renumbering), routerad (router advertisement), routersol (router solicit), timex (time exceeded), toobig (packet too big), unreach (unreachable, whoreq (WRU request), whorep (WRU reply). .SH Stateful Packet Filtering -.PP Stateful packet filtering is where IPFilter remembers some information from one or more packets that it has seen and is able to apply it to future packets that it receives from the network. .PP What this means for each transport layer protocol is different. For TCP it means that if IPFilter sees the very first packet of an attempt to make a connection, it has enough information to allow all other subsequent packets without there needing to be any explicit rules to match them. IPFilter uses the TCP port numbers, TCP flags, window size and sequence numbers to determine which packets should be matched. For UDP, only the UDP port numbers are available. For ICMP, the ICMP types can be combined with the ICMP id field to determine which reply packets match a request/query that has already been seen. For all other protocols, only matching on IP address and protocol number is available for determining if a packet received is a mate to one that has already been let through. .PP The difference this makes is a reduction in the number of rules from 2 or 4 to 1. For example, these 4 rules: .PP .nf pass in on bge0 proto tcp from any to any port = 22 pass out on bge1 proto tcp from any to any port = 22 pass in on bge1 proto tcp from any port = 22 to any pass out on bge0 proto tcp from any port = 22 to any .fi .PP can be replaced with this single rule: .PP .nf pass in on bge0 proto tcp from any to any port = 22 flags S keep state .fi .PP Similar rules for UDP and ICMP might be: .PP .nf pass in on bge0 proto udp from any to any port = 53 keep state pass in on bge0 proto icmp all icmp-type echo keep state .fi .PP When using stateful filtering with TCP it is best to add "flags S" to the rule to ensure that state is only created when a packet is seen that is an indication of a new connection. Although IPFilter can gather some information from packets in the middle of a TCP connection to do stateful filtering, there are some options that are only sent at the start of the connection which alter the valid window of what TCP accepts. The end result of trying to pickup TCP state in mid connection is that some later packets that are part of the connection may not match the known state information and be dropped or blocked, causing problems. If a TCP packet matches IP addresses and port numbers but does not fit into the recognised window, it will not be automatically allowed and will be flagged inside of IPFitler as "out of window" (oow). See below, "Extra packet attributes", for how to match on this attribute. .PP Once a TCP connection has reached the established state, the default timeout allows for it to be idle for 5 days before it is removed from the state table. The timeouts for the other TCP connection states vary from 240 seconds to 30 seconds. Both UDP and ICMP state entries have asymmetric timeouts where the timeout set upon seeing packets in the forward direction is much larger than for the reverse direction. For UDP the default timeouts are 120 and 12 seconds, for ICMP 60 and 6 seconds. This is a reflection of the use of these protocols being more for query-response than for ongoing connections. For all other protocols the timeout is 60 seconds in both directions. .SS Stateful filtering options -.PP The following options can be used with stateful filtering: .HP limit limit the number of state table entries that this rule can create to the number given after limit. A rule that has a limit specified is always permitted that many state table entries, even if creating an additional entry would cause the table to have more entries than the otherwise global limit. .IP .nf pass ... keep state(limit 100) .fi .HP age sets the timeout for the state entry when it sees packets going through it. Additionally it is possible to set the tieout for the reply packets that come back through the firewall to a different value than for the forward path. allowing a short timeout to be set after the reply has been seen and the state no longer required. .RS .PP .nf pass in quick proto icmp all icmp-type echo \\ keep state (age 3) pass in quick proto udp from any \\ to any port = 53 keep state (age 30/1) .fi .RE .HP strict only has an impact when used with TCP. It forces all packets that are allowed through the firewall to be sequential: no out of order delivery of packets is allowed. This can cause significant slowdown for some connections and may stall others. Use with caution. .IP .nf pass in proto tcp ... keep state(strict) .fi .HP noicmperr prevents ICMP error packets from being able to match state table entries created with this flag using the contents of the original packet included. .IP .nf pass ... keep state(noicmperr) .fi .HP sync indicates to IPFilter that it needs to provide information to the user land daemons responsible for syncing other machines state tables up with this one. .IP .nf pass ... keep state(sync) .fi .HP nolog do not generate any log records for the creation or deletion of state table entries. .IP .nf pass ... keep state(nolog) .fi .HP icmp-head rather than just precent ICMP error packets from being able to match state table entries, allow an ACL to be processed that can filter in or out ICMP error packets based as you would with normal firewall rules. The icmp-head option requires a filter rule group number or name to be present, just as you would use with head. .RS .PP .nf pass in quick proto tcp ... keep state(icmp-head 101) block in proto icmp from 10.0.0.0/8 to any group 101 .fi .RE .HP max-srcs allows the number of distinct hosts that can create a state entry to be defined. .IP .nf pass ... keep state(max-srcs 100) pass ... keep state(limit 1000, max-srcs 100) .fi .HP max-per-src whilst max-srcs limits the number of individual hosts that may cause the creation of a state table entry, each one of those hosts is still table to fill up the state table with new entries until the global maximum is reached. This option allows the number of state table entries per address to be limited. .IP .nf pass ... keep state(max-srcs 100, max-per-src 1) pass ... keep state(limit 100, max-srcs 100, max-per-src 1) .fi .IP Whilst these two rules might seem identical, in that they both ultimately limit the number of hosts and state table entries created from the rule to 100, there is a subtle difference: the second will always allow up to 100 state table entries to be created whereas the first may not if the state table fills up from other rules. .IP Further, it is possible to specify a netmask size after the per-host limit that enables the per-host limit to become a per-subnet or per-network limit. .IP .nf pass ... keep state(max-srcs 100, max-per-src 1/24) .fi .IP If there is no IP protocol implied by addresses or other features of the rule, IPFilter will assume that no netmask is an all ones netmask for both IPv4 and IPv6. .SS Tieing down a connection -.PP For any connection that transits a firewall, each packet will be seen twice: once going in and once going out. Thus a connection has 4 flows of packets: .HP forward inbound packets .HP forward outbound packets .HP reverse inbound packets .HP reverse outbound packets .PP IPFilter allows you to define the network interface to be used at all four points in the flow of packets. For rules that match inbound packets, out-via is used to specify which interfaces the packets go out, For rules that match outbound packets, in-via is used to match the inbound packets. In each case, the syntax generalises to this: .PP .nf pass ... in on forward-in,reverse-in \\ out-via forward-out,reverse-out ... pass ... out on forward-out,reverse-out \\ in-via forward-in,reverse-in ... .fi .PP An example that pins down all 4 network interfaces used by an ssh connection might look something like this: .PP .nf pass in on bge0,bge1 out-via bge1,bge0 proto tcp \\ from any to any port = 22 flags S keep state .fi .SS Working with packet fragments -.PP Fragmented packets result in 1 packet containing all of the layer 3 and 4 header information whilst the data is split across a number of other packets. .PP To enforce access control on fragmented packets, one of two approaches can be taken. The first is to allow through all of the data fragments (those that made up the body of the original packet) and rely on matching the header information in the "first" fragment, when it is seen. The reception of body fragments without the first will result in the receiving host being unable to completely reassemble the packet and discarding all of the fragments. The following three rules deny all fragmented packets from being received except those that are UDP and even then only allows those destined for port 2049 to be completed. .PP .nf block in all with frags pass in proto udp from any to any with frag-body pass in proto udp from any to any port = 2049 with frags .fi .PP Another mechanism that is available is to track "fragment state". This relies on the first fragment of a packet that arrives to be the fragment that contains all of the layer 3 and layer 4 header information. With the receipt of that fragment before any other, it is possible to determine which other fragments are to be allowed through without needing to explicitly allow all fragment body packets. An example of how this is done is as follows: .PP .nf pass in proto udp from any port = 2049 to any with frags keep frags .fi .SH Building a tree of rules -.PP Writing your filter rules as one long list of rules can be both inefficient in terms of processing the rules and difficult to understand. To make the construction of filter rules easier, it is possible to place them in groups. A rule can be both a member of a group and the head of a new group. .PP Using filter groups requires at least two rules: one to be in the group one one to send matching packets to the group. If a packet matches a filter rule that is a group head but does not match any of the rules in that group, then the packet is considered to have matched the head rule. .PP Rules that are a member of a group contain the word group followed by either a name or number that defines which group they're in. Rules that form the branch point or starting point for the group must use the word head, followed by either a group name or number. If rules are loaded in that define a group but there is no matching head then they will effectively be orphaned rules. It is possible to have more than one head rule point to the same group, allowing groups to be used like subroutines to implement specific common policies. .PP A common use of filter groups is to define head rules that exist in the filter "main line" for each direction with the interfaces in use. For example: .PP .nf block in quick on bge0 all head 100 block out quick on bge0 all head 101 block in quick on fxp0 all head internal-in block out quick on fxp0 all head internal-out pass in quick proto icmp all icmp-type echo group 100 .fi .PP In the above set of rules, there are four groups defined but only one of them has a member rule. The only packets that would be allowed through the above ruleset would be ICMP echo packets that are received on bge0. .PP Rules can be both a member of a group and the head of a new group, allowing groups to specialise. .PP .nf block in quick on bge0 all head 100 block in quick proto tcp all head 1006 group 100 .fi .PP Another use of filter rule groups is to provide a place for rules to be dynamically added without needing to worry about their specific ordering amongst the entire ruleset. For example, if I was using this simple ruleset: .PP .nf block in quick all with bad block in proto tcp from any to any port = smtp head spammers pass in quick proto tcp from any to any port = smtp flags S keep state .fi .PP and I was getting lots of connections to my email server from 10.1.1.1 to deliver spam, I could load the following rule to complement the above: .IP .nf block in quick from 10.1.1.1 to any group spammers .fi .SS Decapsulation -.PP Rule groups also form a different but vital role for decapsulation rules. With the following simple rule, if IPFilter receives an IP packet that has an AH header as its layer 4 payload, IPFilter would adjust its view of the packet internally and then jump to group 1001 using the data beyond the AH header as the new transport header. .PP .nf decapsulate in proto ah all head 1001 .fi .PP For protocols that are recognised as being used with tunnelling or otherwise encapsulating IP protocols, IPFilter is able to decide what it has on the inside without any assistance. Some tunnelling protocols use UDP as the transport mechanism. In this case, it is necessary to instruct IPFilter as to what protocol is inside UDP. .PP .nf decapsulate l5-as(ip) in proto udp from any \\ to any port = 1520 head 1001 .fi .PP Currently IPFilter only supports finding IPv4 and IPv6 headers directly after the UDP header. .PP If a packet matches a decapsulate rule but fails to match any of the rules that are within the specified group, processing of the packet continues to the next rule after the decapsulate and IPFilter's internal view of the packet is returned to what it was prior to the decapsulate rule. .PP It is possible to construct a decapsulate rule without the group head at the end that ipf(8) will accept but such rules will not result in anything happening. .SS Policy Based Routing -.PP With firewalls being in the position they often are, at the boundary of different networks connecting together and multiple connections that have different properties, it is often desirable to have packets flow in a direction different to what the routing table instructs the kernel. These decisions can often be extended to changing the route based on both source and destination address or even port numbers. .PP To support this kind of configuration, IPFilter allows the next hop destination to be specified with a filter rule. The next hop is given with the interface name to use for output. The syntax for this is interface:ip.address. It is expected that the address given as the next hop is directly connected to the network to which the interface is. .PP .nf pass in on bge0 to bge1:1.1.1.1 proto tcp \\ from 1.1.2.3 to any port = 80 flags S keep state .fi .PP When this feature is combined with stateful filtering, it becomes possible to influence the network interface used to transmit packets in both directions because we now have a sense for what its reverse flow of packets is. .PP .nf pass in on bge0 to bge1:1.1.1.1 reply-to hme1:2.1.1.2 \\ proto tcp from 1.1.2.3 to any port = 80 flags S keep state .fi .PP If the actions of the routing table are perfectly acceptable, but you would like to mask the presence of the firewall by not changing the TTL in IP packets as they transit it, IPFilter can be instructed to do a "fastroute" action like this: .PP .nf pass in on bge0 fastroute proto icmp all .fi .PP This should be used with caution as it can lead to endless packet loops. Additionally, policy based routing does not change the IP header's TTL value. .PP A variation on this type of rule supports a duplicate of the original packet being created and sent out a different network. This can be useful for monitoring traffic and other purposes. .PP .nf pass in on bge0 to bge1:1.1.1.1 reply-to hme1:2.1.1.2 \\ dup-to fxp0:10.0.0.1 proto tcp from 1.1.2.3 \\ to any port = 80 flags S keep state .fi .SS Matching IPv4 options -.PP The design for IPv4 allows for the header to be upto 64 bytes long, however most traffic only uses the basic header which is 20 bytes long. The other 44 bytes can be used to store IP options. These options are generally not necessary for proper interaction and function on the Internet today. For most people it is sufficient to block and drop all packets that have any options set. This can be achieved with this rule: .PP .nf block in quick all with ipopts .fi .PP This rule is usually placed towards the top of the configuration so that all incoming packets are blocked. .PP If you wanted to allow in a specific IP option type, the syntax changes slightly: .PP .nf pass in quick proto igmp all with opt rtralrt .fi .PP The following is a list of IP options that most people encounter and what their use/threat is. .HP lsrr (loose source route) the sender of the packet includes a list of addresses that they wish the packet to be routed through to on the way to the destination. Because replies to such packets are expected to use the list of addresses in reverse, hackers are able to very effectively use this header option in address spoofing attacks. .HP rr (record route) the sender allocates some buffer space for recording the IP address of each router that the packet goes through. This is most often used with ping, where the ping response contains a copy of all addresses from the original packet, telling the sender what route the packet took to get there. Due to performance and security issues with IP header options, this is almost no longer used. .HP rtralrt (router alert) this option is often used in IGMP messages as a flag to routers that the packet needs to be handled differently. It is unlikely to ever be received from an unknown sender. It may be found on LANs or otherwise controlled networks where the RSVP protocol and multicast traffic is in heavy use. .HP ssrr (strict source route) the sender of the packet includes a list of addresses that they wish the packet to be routed through to on the way to the destination. Where the lsrr option allows the sender to specify only some of the nodes the packet must go through, with the ssrr option, every next hop router must be specified. .PP The complete list of IPv4 options that can be matched on is: addext (Address Extension), cipso (Classical IP Security Option), dps (Dynamic Packet State), e-sec (Extended Security), eip (Extended Internet Protocol), encode (ENCODE), finn (Experimental Flow Control), imitd (IMI Traffic Descriptor), lsrr (Loose Source Route), mtup (MTU Probe - obsolete), mtur (MTU response - obsolete), nop (No Operation), nsapa (NSAP Address), rr (Record Route), rtralrt (Router Alert), satid (Stream Identifier), sdb (Selective Directed Broadcast), sec (Security), ssrr (Strict Source Route), tr (Tracerote), ts (Timestamp), ump (Upstream Multicast Packet), visa (Experimental Access Control) and zsu (Experimental Measurement). .SS Security with CIPSO and IPSO -.PP IPFilter supports filtering on IPv4 packets using security attributes embedded in the IP options part of the packet. These options are usually only used on networks and systems that are using lablled security. Unless you know that you are using labelled security and your networking is also labelled, it is highly unlikely that this section will be relevant to you. .PP With the traditional IP Security Options (IPSO), packets can be tagged with a security level. The following keywords are recognised and match with the relevant RFC with respect to the bit patterns matched: confid (confidential), rserve-1 (1st reserved value), rserve-2 (2nd reserved value), rserve-3 (3rd reserved value), rserve-4 (4th reserved value), secret (secret), topsecret (top secret), unclass (unclassified). .PP .nf block in quick all with opt sec-class unclass pass in all with opt sec-class secret .fi .SS Matching IPv6 extension headers -.PP Just as it is possible to filter on the various IPv4 header options, so too it is possible to filter on the IPv6 extension headers that are placed between the IPv6 header and the transport protocol header. .PP dstopts (destination options), esp (encrypted, secure, payload), frag (fragment), hopopts (hop-by-hop options), ipv6 (IPv6 header), mobility (IP mobility), none, routing. .SS Logging -.PP There are two ways in which packets can be logged with IPFilter. The first is with a rule that specifically says log these types of packets and the second is a qualifier to one of the other keywords. Thus it is possible to both log and allow or deny a packet with a single rule. .PP .nf pass in log quick proto tcp from any to any port = 22 .fi .PP When using stateful filtering, the log action becomes part of the result that is remembered about a packet. Thus if the above rule was qualified with keep state, every packet in the connection would be logged. To only log the first packet from every packet flow tracked with keep state, it is necessary to indicate to IPFilter that you only wish to log the first packet. .PP .nf pass in log first quick proto tcp from any to any port = 22 \\ flags S keep state .fi .PP If it is a requirement that the logging provide an accurate representation of which connections are allowed, the log action can be qualified with the option or-block. This allows the administrator to instruct IPFilter to block the packet if the attempt to record the packet in IPFilter's kernel log records (which have an upper bound on size) failed. Unless the system shuts down or reboots, once a log record is written into the kernel buffer, it is there until ipmon(8) reads it. .PP .nf block in log proto tcp from any to any port = smtp pass in log or-block first quick proto tcp from any \\ to any port = 22 flags S keep state .fi .PP By default, IPFilter will only log the header portion of a packet received on the network. Up to 128 bytes of a packet's body can also be logged with the body keyword. ipmon(8) will display the contents of the portion of the body logged in hex. .PP .nf block in log body proto icmp all .fi .PP When logging packets from ipmon(8) to syslog, by default ipmon(8) will control what syslog facility and priority a packet will be logged with. This can be tuned on a per rule basis like this: .PP .nf block in quick log level err all with bad pass in log level local1.info proto tcp \\ from any to any port = 22 flags S keep state .fi .PP ipfstat(8) reports how many packets have been successfully logged and how many failed attempts to log a packet there were. .SS Filter rule comments -.PP If there is a desire to associate a text string, be it an administrative comment or otherwise, with an IPFilter rule, this can be achieved by giving the filter rule a comment. The comment is loaded with the rule into the kernel and can be seen when the rules are listed with ipfstat. .PP .nf pass in quick proto tcp from any \\ to port = 80 comment "all web server traffic is ok" pass out quick proto tcp from any port = 80 \\ to any comment "all web server traffic is ok" .fi .SS Tags -.PP To enable filtering and NAT to correctly match up packets with rules, tags can be added at with NAT (for inbound packets) and filtering (for outbound packets.) This allows a filter to be correctly mated with its NAT rule in the event that the NAT rule changed the packet in a way that would mean it is not obvious what it was. .PP For inbound packets, IPFilter can match the tag used in the filter rules with that set by NAT. For outbound rules, it is the reverse, the filter sets the tag and the NAT rule matches up with it. .PP .nf pass in ... match-tag(nat=proxy) pass out ... set-tag(nat=proxy) .fi .PP Another use of tags is to supply a number that is only used with logging. When packets match these rules, the log tag is carried over into the log file records generated by ipmon(8). With the correct use of tools such as grep, extracting log records of interest is simplified. .PP .nf block in quick log ... set-tag(log=33) .fi .SH Filter Rule Expiration -.PP IPFilter allows rules to be added into the kernel that it will remove after a specific period of time by specifying rule-ttl at the end of a rule. When listing rules in the kernel using ipfstat(8), rules that are going to expire will NOT display "rule-ttl" with the timeout, rather what will be seen is a comment with how many ipfilter ticks left the rule has to live. .PP The time to live is specified in seconds. .PP .nf pass in on fxp0 proto tcp from any \\ to port = 22 flags S keep state rule-ttl 30 .fi .SH Internal packet attributes -.PP In addition to being able to filter on very specific network and transport header fields, it is possible to filter on other attributes that IPFilter attaches to a packet. These attributes are placed in a rule after the keyword "with", as can be seen with frags and frag-body above. The following is a list of the other attributes available: .HP oow the packet's IP addresses and TCP ports match an existing entry in the state table but the sequence numbers indicate that it is outside of the accepted window. .IP .nf block return-rst in quick proto tcp from any to any with not oow .fi .HP bcast this is set by IPFilter when it receives notification that the link layer packet was a broadcast packet. No checking of the IP addresses is performned to determine if it is a broadcast destination or not. .IP .nf block in quick proto udp all with bcast .fi .HP mcast this is set by IPFilter when it receives notification that the link layer packet was a multicast packet. No checking of the IP addresses is performned to determine if it is a multicast destination or not. .IP .nf pass in quick proto udp from any to any port = dns with mcast .fi .HP mbcast can be used to match a packet that is either a multicast or broadcast packet at the link layer, as indicated by the operating system. .IP .nf pass in quick proto udp from any to any port = ntp with mbcast .fi .HP nat the packet positively matched a NAT table entry. .HP bad sanity checking of the packet failed. This could indicate that the layer 3/4 headers are not properly formed. .HP bad-src when reverse path verification is enabled, this flag will be set when the interface the packet is received on does not match that which would be used to send a packet out of to the source address in the received packet. .HP bad-nat an attempt to perform NAT on the packet failed. .HP not each one of the attributes matched using the "with" keyword can also be looked for to not be present. For example, to only allow in good packets, I can do this: .PP .nf block in all pass in all with not bad .fi .SH Tuning IPFilter -.PP The ipf.conf file can also be used to tune the behaviour of IPFilter, allowing, for example, timeouts for the NAT/state table(s) to be set along with their sizes. The presence and names of tunables may change from one release of IPFilter to the next. The tunables that can be changed via ipf.conf is the same as those that can be seen and modified using the -T command line option to ipf(8). .PP NOTE: When parsing ipf.conf, ipf(8) will apply the settings before loading any rules. Thus if your settings are at the top, these may be applied whilst the rules not applied if there is an error further down in the configuration file. .PP To set one of the values below, the syntax is simple: "set", followed by the name of the tuneable to set and then the value to set it to. .PP .nf set state_max 9999; set state_size 10101; .fi .PP A list of the currently available variables inside IPFilter that may be tuned from ipf.conf are as follows: .HP active set through -s command line switch of ipf(8). See ipf(8) for details. .HP chksrc when set, enables reverse path verification on source addresses and for filters to match packets with bad-src attribute. .HP control_forwarding when set turns off kernel forwarding when IPFilter is disabled or unloaded. .HP default_pass the default policy - whether packets are blocked or passed, etc - is represented by the value of this variable. It is a bit field and the bits that can be set are found in . It is not recommended to tune this value directly. .HP ftp_debug set the debugging level of the in-kernel FTP proxy. Debug messages will be printed to the system console. .HP ftp_forcepasv when set the FTP proxy must see a PASV/EPSV command before creating the state/NAT entries for the 227 response. .HP ftp_insecure when set the FTP proxy will not wait for a user to login before allowing data connections to be created. .HP ftp_pasvonly when set the proxy will not create state/NAT entries for when it sees either the PORT or EPRT command. .HP ftp_pasvrdr when enabled causes the FTP proxy to create very insecure NAT/state entries that will allow any connection between the client and server hosts when a 227 reply is seen. Use with extreme caution. .HP ftp_single_xfer when set the FTP proxy will only allow one data connection at a time. .HP hostmap_size sets the size of the hostmap table used by NAT to store address mappings for use with sticky rules. .HP icmp_ack_timeout default timeout used for ICMP NAT/state when a reply packet is seen for an ICMP state that already exists .HP icmp_minfragmtu sets the minimum MTU that is considered acceptable in an ICMP error before deciding it is a bad packet. .HP icmp_timeout default timeout used for ICMP NAT/state when the packet matches the rule .HP ip_timeout default timeout used for NAT/state entries that are not TCP/UDP/ICMP. .HP ipf_flags .HP ips_proxy_debug this sets the debugging level for the proxy support code. When enabled, debugging messages will be printed to the system console. .HP log_all when set it changes the behaviour of "log body" to log the entire packet rather than just the first 128 bytes. .HP log_size sets the size of the in-kernel log buffer in bytes. .HP log_suppress when set, IPFilter will check to see if the packet it is logging is similar to the one it previously logged and if so, increases the occurrence count for that packet. The previously logged packet must not have yet been read by ipmon(8). .HP min_ttl is used to set the TTL value that packets below will be marked with the low-ttl attribute. .HP nat_doflush if set it will cause the NAT code to do a more aggressive flush of the NAT table at the next opportunity. Once the flush has been done, the value is reset to 0. .HP nat_lock this should only be changed using ipfs(8) .HP nat_logging when set, NAT will create log records that can be read from /dev/ipnat. .HP nat_maxbucket maximum number of entries allowed to exist in each NAT hash bucket. This prevents an attacker trying to load up the hash table with entries in a single bucket, reducing performance. .HP nat_rules_size size of the hash table to store map rules. .HP nat_table_max maximum number of entries allowed into the NAT table .HP nat_table_size size of the hash table used for NAT .HP nat_table_wm_high when the fill percentage of the NAT table exceeds this mark, more aggressive flushing is enabled. .HP nat_table_wm_low this sets the percentage at which the NAT table's aggressive flushing will turn itself off. .HP rdr_rules_size size of the hash table to store rdr rules. .HP state_lock this should only be changed using ipfs(8) .HP state_logging when set, the stateful filtering will create log records that can be read from /dev/ipstate. .HP state_max maximum number of entries allowed into the state table .HP state_maxbucket maximum number of entries allowed to exist in each state hash bucket. This prevents an attacker trying to load up the hash table with entries in a single bucket, reducing performance. .HP state_size size of the hash table used for stateful filtering .HP state_wm_freq this controls how often the aggressive flushing should be run once the state table exceeds state_wm_high in percentage full. .HP state_wm_high when the fill percentage of the state table exceeds this mark, more aggressive flushing is enabled. .HP state_wm_low this sets the percentage at which the state table's aggressive flushing will turn itself off at. .HP tcp_close_wait timeout used when a TCP state entry reaches the FIN_WAIT_2 state. .HP tcp_closed timeout used when a TCP state entry is ready to be removed after either a RST packet is seen. .HP tcp_half_closed timeout used when a TCP state entry reaches the CLOSE_WAIT state. .HP tcp_idle_timeout timeout used when a TCP state entry reaches the ESTABLISHED state. .HP tcp_last_ack timeout used when a TCP NAT/state entry reaches the LAST_ACK state. .HP tcp_syn_received timeout applied to a TCP NAT/state entry after SYN-ACK packet has been seen. .HP tcp_syn_sent timeout applied to a TCP NAT/state entry after SYN packet has been seen. .HP tcp_time_wait timeout used when a TCP NAT/state entry reaches the TIME_WAIT state. .HP tcp_timeout timeout used when a TCP NAT/state entry reaches either the half established state (one ack is seen after a SYN-ACK) or one side is in FIN_WAIT_1. .HP udp_ack_timeout default timeout used for UDP NAT/state when a reply packet is seen for a UDP state that already exists .HP udp_timeout default timeout used for UDP NAT/state when the packet matches the rule .HP update_ipid when set, turns on changing the IP id field in NAT'd packets to a random number. .SS Table of visible variables -.PP A list of all of the tunables, their minimum, maximum and current values is as follows. .PP .nf Name Min Max Current active 0 0 0 chksrc 0 1 0 control_forwarding 0 1 0 default_pass 0 MAXUINT 134217730 ftp_debug 0 10 0 ftp_forcepasv 0 1 1 ftp_insecure 0 1 0 ftp_pasvonly 0 1 0 ftp_pasvrdr 0 1 0 ftp_single_xfer 0 1 0 hostmap_size 1 MAXINT 2047 icmp_ack_timeout 1 MAXINT 12 icmp_minfragmtu 0 1 68 icmp_timeout 1 MAXINT 120 ip_timeout 1 MAXINT 120 ipf_flags 0 MAXUINT 0 ips_proxy_debug 0 10 0 log_all 0 1 0 log_size 0 524288 32768 log_suppress 0 1 1 min_ttl 0 1 4 nat_doflush 0 1 0 nat_lock 0 1 0 nat_logging 0 1 1 nat_maxbucket 1 MAXINT 22 nat_rules_size 1 MAXINT 127 nat_table_max 1 MAXINT 30000 nat_table_size 1 MAXINT 2047 nat_table_wm_high 2 100 99 nat_table_wm_low 1 99 90 rdr_rules_size 1 MAXINT 127 state_lock 0 1 0 state_logging 0 1 1 state_max 1 MAXINT 4013 state_maxbucket 1 MAXINT 26 state_size 1 MAXINT 5737 state_wm_freq 2 999999 20 state_wm_high 2 100 99 state_wm_low 1 99 90 tcp_close_wait 1 MAXINT 480 tcp_closed 1 MAXINT 60 tcp_half_closed 1 MAXINT 14400 tcp_idle_timeout 1 MAXINT 864000 tcp_last_ack 1 MAXINT 60 tcp_syn_received 1 MAXINT 480 tcp_syn_sent 1 MAXINT 480 tcp_time_wait 1 MAXINT 480 tcp_timeout 1 MAXINT 480 udp_ack_timeout 1 MAXINT 24 udp_timeout 1 MAXINT 240 update_ipid 0 1 0 .fi .SH Calling out to internal functions -.PP IPFilter provides a pair of functions that can be called from a rule that allow for a single rule to jump out to a group rather than walk through a list of rules to find the group. If you've got multiple networks, each with its own group of rules, this feature may help provide better filtering performance. .PP The lookup to find which rule group to jump to is done on either the source address or the destination address but not both. .PP In this example below, we are blocking all packets by default but then doing a lookup on the source address from group 1010. The two rules in the ipf.conf section are lone members of their group. For an incoming packet that is from 1.1.1.1, it will go through three rules: (1) the block rule, (2) the call rule and (3) the pass rule for group 1020. For a packet that is from 3.3.2.2, it will also go through three rules: (1) the block rule, (2) the call rule and (3) the pass rule for group 1030. Should a packet from 3.1.1.1 arrive, it will be blocked as it does not match any of the entries in group 1010, leaving it to only match the first rule. .PP .nf from ipf.conf ------------- block in all call now srcgrpmap/1010 in all pass in proto tcp from any to any port = 80 group 1020 pass in proto icmp all icmp-type echo group 1030 from ippool.conf ---------------- group-map in role=ipf number=1010 { 1.1.1.1 group = 1020, 3.3.0.0/16 group = 1030; }; .fi .SS IPFilter matching expressions -.PP An experimental feature that has been added to filter rules is to use the same expression matching that is available with various commands to flush and list state/NAT table entries. The use of such an expression precludes the filter rule from using the normal IP header matching. .PP .nf pass in exp { "tcp.sport 23 or tcp.sport 50" } keep state .fi .SS Filter rules with BPF -.PP On platforms that have the BPF built into the kernel, IPFilter can be built to allow BPF expressions in filter rules. This allows for packet matching to be on arbitrary data in the packt. The use of a BPF expression replaces all of the other protocol header matching done by IPFilter. .PP .nf pass in bpf-v4 { "tcp and (src port 23 or src port 50)" } \\ keep state .fi .PP These rules tend to be write-only because the act of compiling the filter expression into the BPF instructions loaded into the kernel can make it difficut to accurately reconstruct the original text filter. The end result is that while ipf.conf() can be easy to read, understanding the output from ipfstat might not be. .SH VARIABLES -.PP This configuration file, like all others used with IPFilter, supports the use of variable substitution throughout the text. .PP .nf nif="ppp0"; pass in on $nif from any to any .fi .PP would become .PP .nf pass in on ppp0 from any to any .fi .PP Variables can be used recursively, such as 'foo="$bar baz";', so long as $bar exists when the parser reaches the assignment for foo. .PP See .B ipf(8) for instructions on how to define variables to be used from a shell environment. .DT .SH FILES /dev/ipf /etc/ipf.conf .br /usr/share/examples/ipfilter Directory with examples. .SH SEE ALSO ipf(8), ipfstat(8), ippool.conf(5), ippool(8) diff --git a/sbin/ipf/ipf/ipf.8 b/sbin/ipf/ipf/ipf.8 index 38cac51435d1..fba145b0c785 100644 --- a/sbin/ipf/ipf/ipf.8 +++ b/sbin/ipf/ipf/ipf.8 @@ -1,184 +1,181 @@ .TH IPF 8 .SH NAME ipf \- alters packet filtering lists for IP packet input and output .SH SYNOPSIS .B ipf [ .B \-6AcdDEInoPrsvVyzZ ] [ .B \-l ] [ .B \-T ] [ .B \-F ] .B \-f <\fIfilename\fP> [ .B \-f <\fIfilename\fP> [...]] .SH DESCRIPTION -.PP \fBipf\fP opens the filenames listed (treating "\-" as stdin) and parses the file for a set of rules which are to be added or removed from the packet filter rule set. .PP Each rule processed by \fBipf\fP is added to the kernel's internal lists if there are no parsing problems. Rules are added to the end of the internal lists, matching the order in which they appear when given to \fBipf\fP. .SH OPTIONS .TP .B \-6 IPv4 and IPv6 rules are stored in a single table and can be read from a single file. This option is no longer required to load IPv6 rules. This option is ignored when specified with the -F option and the -F option will flush IPv4 rules even if this option is specified. .TP .B \-A Set the list to make changes to the active list (default). .TP .B \-c This option causes \fBipf\fP to generate output files for a compiler that supports \fBlanguage\fI. At present, the only target language supported is \fBC\fB (-cc) for which two files - \fBip_rules.c\fP and \fBip_rules.h\fP are generated in the \fBCURRENT DIRECTORY\fP when \fBipf\fP is being run. These files can be used with the \fBIPFILTER_COMPILED\fP kernel option to build filter rules statically into the kernel. .TP .B \-d Turn debug mode on. Causes a hexdump of filter rules to be generated as it processes each one. .TP .B \-D Disable the filter (if enabled). Not effective for loadable kernel versions. .TP .B \-E Enable the filter (if disabled). Not effective for loadable kernel versions. .TP .BR \-F \0 This option specifies which filter list to flush. The parameter should either be "i" (input), "o" (output) or "a" (remove all filter rules). Either a single letter or an entire word starting with the appropriate letter maybe used. This option maybe before, or after, any other with the order on the command line being that used to execute options. .TP .BR \-F \0 To flush entries from the state table, the \fB-F\fP option is used in conjunction with either "s" (removes state information about any non-fully established connections) or "S" (deletes the entire state table). Only one of the two options may be given. A fully established connection will show up in \fBipfstat -s\fP output as 5/5, with deviations either way indicating it is not fully established any more. .TP .BR \-F <5|6|7|8|9|10|11> For the TCP states that represent the closing of a connection has begun, be it only one side or the complete connection, it is possible to flush those states directly using the number corresponding to that state. The numbers relate to the states as follows: 5 = close-wait, 6 = fin-wait-1, 7 = closing, 8 = last-ack, 9 = fin-wait-2, 10 = time-wait, 11 = closed. .TP .BR \-F If the argument supplied to \fB-F\fP is greater than 30, then state table entries that have been idle for more than this many seconds will be flushed. .TP .BR \-f \0 This option specifies which files \fBipf\fP should use to get input from for modifying the packet filter rule lists. .TP .B \-I Set the list to make changes to the inactive list. .TP .B \-l \0 Use of the \fB-l\fP flag toggles default logging of packets. Valid arguments to this option are \fBpass\fP, \fBblock\fP and \fBnomatch\fP. When an option is set, any packet which exits filtering and matches the set category is logged. This is most useful for causing all packets which don't match any of the loaded rules to be logged. .TP .B \-n This flag (no-change) prevents \fBipf\fP from actually making any ioctl calls or doing anything which would alter the currently running kernel. .TP .B \-o Force rules by default to be added/deleted to/from the output list, rather than the (default) input list. .TP .B \-P Add rules as temporary entries in the authentication rule table. .TP .B \-r Remove matching filter rules rather than add them to the internal lists .TP .B \-s Swap the active filter list in use to be the "other" one. .TP .B \-T This option allows run-time changing of IPFilter kernel variables. Some variables require IPFilter to be in a disabled state (\fB-D\fP) for changing, others do not. The optionlist parameter is a comma separated list of tuning commands. A tuning command is either "list" (retrieve a list of all variables in the kernel, their maximum, minimum and current value), a single variable name (retrieve its current value) and a variable name with a following assignment to set a new value. Some examples follow. .nf # Print out all IPFilter kernel tunable parameters ipf -T list # Display the current TCP idle timeout and then set it to 3600 ipf -D -T fr_tcpidletimeout,fr_tcpidletimeout=3600 -E # Display current values for fr_pass and fr_chksrc, then set fr_chksrc to 1. ipf -T fr_pass,fr_chksrc,fr_chksrc=1 .fi .TP .B \-v Turn verbose mode on. Displays information relating to rule processing. .TP .B \-V Show version information. This will display the version information compiled into the ipf binary and retrieve it from the kernel code (if running/present). If it is present in the kernel, information about its current state will be displayed (whether logging is active, default filtering, etc). .TP .B \-y Manually resync the in-kernel interface list maintained by IP Filter with the current interface status list. .TP .B \-z For each rule in the input file, reset the statistics for it to zero and display the statistics prior to them being zeroed. .TP .B \-Z Zero global statistics held in the kernel for filtering only (this doesn't affect fragment or state statistics). .DT .SH ENVIRONMENT .B ipf utilizes the following environment variable. .TP .B IPF_PREDEFINED ipfilter variables, see VARIABLES in ipf(5), can be specified in this environment variable providing shell access to ipfilter and ipnat variables. For example, .br IPF_PREDEFINED='my_server="10.1.1.1"; my_client="10.1.1.2";' .SH FILES /dev/ipauth .br /dev/ipl .br /dev/ipstate .SH SEE ALSO ipftest(1), mkfilters(1), ipf(4), ipl(4), ipf(5), ipfstat(8), ipmon(8), ipnat(8) .SH DIAGNOSTICS -.PP Needs to be run as root for the packet filtering lists to actually be affected inside the kernel. .SH BUGS -.PP If you find any, please send email to me at darrenr@pobox.com diff --git a/sbin/ipf/ipf/ipfilter.5 b/sbin/ipf/ipf/ipfilter.5 index 0bba0f4bad02..0a1da67d70cd 100644 --- a/sbin/ipf/ipf/ipfilter.5 +++ b/sbin/ipf/ipf/ipfilter.5 @@ -1,10 +1,9 @@ .TH IPFILTER 1 .SH NAME IP Filter .SH DESCRIPTION -.PP IP Filter is a package providing packet filtering capabilities for a variety of operating systems. On a properly setup system, it can be used to build a firewall. .SH SEE ALSO ipf(8), ipf(1), ipf(5), ipnat(8), ipnat(5), mkfilters(1) diff --git a/sbin/ipf/ipfs/ipfs.8 b/sbin/ipf/ipfs/ipfs.8 index a58d02db078a..cf668cc09400 100644 --- a/sbin/ipf/ipfs/ipfs.8 +++ b/sbin/ipf/ipfs/ipfs.8 @@ -1,126 +1,123 @@ .\" .TH IPFS 8 .SH NAME ipfs \- saves and restores information for NAT and state tables. .SH SYNOPSIS .B ipfs [-nv] -l .PP .B ipfs [-nv] -u .PP .B ipfs [-nv] [ .B \-d <\fIdirname\fP> ] -R .PP .B ipfs [-nv] [ .B \-d <\fIdirname\fP> ] -W .PP .B ipfs [-nNSv] [ .B \-f <\fIfilename\fP> ] -r .PP .B ipfs [-nNSv] [ .B \-f <\fIfilename\fP> ] -w .PP .B ipfs [-nNSv] .B \-f <\fIfilename\fP> .B \-i , .SH DESCRIPTION -.PP \fBipfs\fP allows state information created for NAT entries and rules using \fIkeep state\fP to be locked (modification prevented) and then saved to disk, allowing for the system to experience a reboot, followed by the restoration of that information, resulting in connections not being interrupted. .SH OPTIONS .TP .B \-d Change the default directory used with .B \-R and .B \-W options for saving state information. .TP .B \-n Don't actually take any action that would affect information stored in the kernel or on disk. .TP .B \-v Provides a verbose description of what's being done. .TP .B \-i , Change all instances of interface name ifname1 in the state save file to ifname2. Useful if you're restoring state information after a hardware reconfiguration or change. .TP .B \-N Operate on NAT information. .TP .B \-S Operate on filtering state information. .TP .B \-u Unlock state tables in the kernel. .TP .B \-l Lock state tables in the kernel. .TP .B \-r Read information in from the specified file and load it into the kernel. This requires the state tables to have already been locked and does not change the lock once complete. .TP .B \-w Write information out to the specified file and from the kernel. This requires the state tables to have already been locked and does not change the lock once complete. .TP .B \-R Restores all saved state information, if any, from two files, \fIipstate.ipf\fP and \fIipnat.ipf\fP, stored in the \fI/var/db/ipf\fP directory unless otherwise specified by the .B \-d option. The state tables are locked at the beginning of this operation and unlocked once complete. .TP .B \-W Saves in-kernel state information, if any, out to two files, \fIipstate.ipf\fP and \fIipnat.ipf\fP, stored in the \fI/var/db/ipf\fP directory unless otherwise specified by the .B \-d option. The state tables are locked at the beginning of this operation and unlocked once complete. .DT .SH FILES /var/db/ipf/ipstate.ipf .br /var/db/ipf/ipnat.ipf .br /dev/ipl .br /dev/ipstate .br /dev/ipnat .SH SEE ALSO ipf(8), ipl(4), ipmon(8), ipnat(8) .SH DIAGNOSTICS -.PP Perhaps the -W and -R operations should set the locking but rather than undo it, restore it to what it was previously. Fragment table information is currently not saved. .SH BUGS -.PP If you find any, please send email to me at darrenr@pobox.com diff --git a/sbin/ipf/ipftest/ipftest.1 b/sbin/ipf/ipftest/ipftest.1 index 11b64e288600..5c5fe60901a0 100644 --- a/sbin/ipf/ipftest/ipftest.1 +++ b/sbin/ipf/ipftest/ipftest.1 @@ -1,204 +1,203 @@ .TH ipftest 1 .SH NAME ipftest \- test packet filter rules with arbitrary input. .SH SYNOPSIS .B ipftest [ .B \-6bCdDoRvx ] [ .B \-F input-format ] [ .B \-i ] [ .B \-I interface ] [ .B \-l ] [ .B \-N ] [ .B \-P ] [ .B \-r ] [ .B \-S ] [ .B \-T ] .SH DESCRIPTION -.PP \fBipftest\fP is provided for the purpose of being able to test a set of filter rules without having to put them in place, in operation and proceed to test their effectiveness. The hope is that this minimises disruptions in providing a secure IP environment. .PP \fBipftest\fP will parse any standard ruleset for use with \fBipf\fP, \fBipnat\fP and/or \fBippool\fP and apply input, returning output as to the result. However, \fBipftest\fP will return one of three values for packets passed through the filter: pass, block or nomatch. This is intended to give the operator a better idea of what is happening with packets passing through their filter ruleset. .PP At least one of \fB\-N\fP, \fB-P\fP or \fB\-r\fP must be specified. .SH OPTIONS .TP .B \-6 Use IPv6. .TP .B \-b Cause the output to be a brief summary (one-word) of the result of passing the packet through the filter; either "pass", "block" or "nomatch". This is used in the regression testing. .TP .B \-C Force the checksums to be (re)calculated for all packets being input into \fBipftest\fP. This may be necessary if pcap files from tcpdump are being fed in where there are partial checksums present due to hardware offloading. .TP .B \-d Turn on filter rule debugging. Currently, this only shows you what caused the rule to not match in the IP header checking (addresses/netmasks, etc). .TP .B \-D Dump internal tables before exiting. This excludes log messages. .TP .B \-F This option is used to select which input format the input file is in. The following formats are available: etherfind, hex, pcap, snoop, tcpdump,text. .RS .TP .B etherfind The input file is to be text output from etherfind. The text formats which are currently supported are those which result from the following etherfind option combinations: .PP .nf etherfind -n etherfind -n -t .fi .TP .B hex The input file is to be hex digits, representing the binary makeup of the packet. No length correction is made, if an incorrect length is put in the IP header. A packet may be broken up over several lines of hex digits, a blank line indicating the end of the packet. It is possible to specify both the interface name and direction of the packet (for filtering purposes) at the start of the line using this format: [direction,interface] To define a packet going in on le0, we would use \fB[in,le0]\fP - the []'s are required and part of the input syntax. .HP .B pcap The input file specified by \fB\-i\fP is a binary file produced using libpcap (i.e., tcpdump version 3). Packets are read from this file as being input (for rule purposes). An interface maybe specified using \fB\-I\fP. .TP .B snoop The input file is to be in "snoop" format (see RFC 1761). Packets are read from this file and used as input from any interface. This is perhaps the most useful input type, currently. .TP .B tcpdump The input file is to be text output from tcpdump. The text formats which are currently supported are those which result from the following tcpdump option combinations: .PP .nf tcpdump -n tcpdump -nq tcpdump -nqt tcpdump -nqtt tcpdump -nqte .fi .TP .B text The input file is in \fBipftest\fP text input format. This is the default if no \fB\-F\fP argument is specified. The format used is as follows: .nf "in"|"out" "on" if ["tcp"|"udp"|"icmp"] srchost[,srcport] dsthost[,destport] [FSRPAU] .fi .PP This allows for a packet going "in" or "out" of an interface (if) to be generated, being one of the three main protocols (optionally), and if either TCP or UDP, a port parameter is also expected. If TCP is selected, it is possible to (optionally) supply TCP flags at the end. Some examples are: .nf # a UDP packet coming in on le0 in on le0 udp 10.1.1.1,2210 10.2.1.5,23 # an IP packet coming in on le0 from localhost - hmm :) in on le0 localhost 10.4.12.1 # a TCP packet going out of le0 with the SYN flag set. out on le0 tcp 10.4.12.1,2245 10.1.1.1,23 S .fi .RE .DT .TP .BR \-i \0 Specify the filename from which to take input. Default is stdin. .TP .BR \-I \0 Set the interface name (used in rule matching) to be the name supplied. This is useful where it is not otherwise possible to associate a packet with an interface. Normal "text packets" can override this setting. .TP .BR \-l \0 Dump log messages generated during testing to the specified file. .TP .BR \-N \0 Specify the filename from which to read NAT rules in \fBipnat\fP(5) format. .TP .B \-o Save output packets that would have been written to each interface in a file /tmp/\fIinterface_name\fP in raw format. .TP .BR \-P \0 Read IP pool configuration information in \fBippool\fP(5) format from the specified file. .TP .BR \-r \0 Specify the filename from which to read filter rules in \fBipf\fP(5) format. .TP .B \-R Don't attempt to convert IP addresses to hostnames. .TP .BR \-S \0 The IP address specifived with this option is used by ipftest to determine whether a packet should be treated as "input" or "output". If the source address in an IP packet matches then it is considered to be inbound. If it does not match then it is considered to be outbound. This is primarily for use with tcpdump (pcap) files where there is no in/out information saved with each packet. .TP .BR \-T \0 This option simulates the run-time changing of IPFilter kernel variables available with the \fB\-T\fP option of \fBipf\fP. The optionlist parameter is a comma separated list of tuning commands. A tuning command is either "list" (retrieve a list of all variables in the kernel, their maximum, minimum and current value), a single variable name (retrieve its current value) and a variable name with a following assignment to set a new value. See \fBipf\fP(8) for examples. .TP .B \-v Verbose mode. This provides more information about which parts of rule matching the input packet passes and fails. .TP .B \-x Print a hex dump of each packet before printing the decoded contents. .SH SEE ALSO ipf(5), ipf(8), snoop(1m), tcpdump(8), etherfind(8c) .SH BUGS Not all of the input formats are sufficiently capable of introducing a wide enough variety of packets for them to be all useful in testing. diff --git a/sbin/ipf/ipmon/ipmon.5 b/sbin/ipf/ipmon/ipmon.5 index ccca214b26a6..c6a4b6c12a42 100644 --- a/sbin/ipf/ipmon/ipmon.5 +++ b/sbin/ipf/ipmon/ipmon.5 @@ -1,225 +1,222 @@ .\" .TH IPMON 5 .SH NAME ipmon, ipmon.conf \- ipmon configuration file format .SH DESCRIPTION The .B ipmon.conf file is optionally loaded by .B ipmon when it starts. Its primary purpose is to direct .B ipmon to do extra actions when it sees a specific log entry from the kernel. .PP A line in the .B ipmon.conf file is either a comment or a .B match line. Each line must have a matching segment and an action segment. These are to the left and right of the word "do", respectively. A comment line is any line that starts with a #. .PP .B NOTE: This file differs from all other IPFilter configuration files because it attempts to match every line with every log record received. It does .B not stop at the .B first match or only use the .B last match. .PP For the action segment, a .B match line can delivery output to one of three destinations: \fBfile\fR, \fBemail\fR or \fBcommand\fR. For example: .nf match { type = ipf; } do { save("file:///var/log/ipf-log"); }; match { type = nat; } do { syslog; }; match { type = state; } do { execute("/bin/mail root"); }; .fi .PP and is roughly described like this: .PP match { \fImatch-it ,match-it, ...\fP } do { \fIaction, action, ...\fP}; .PP where there can be a list of matching expressions and a list of actions to perform if all of the matching expressions are matched up with by the current log entry. .PP The lines above would save all ipf log entries to /var/log/ipf-log, send all of the entries for NAT (ipnat related) to syslog and generate an email to root for each log entry from the state tables. .SH SYNTAX - MATCHING -.PP In the above example, the matching segment was confined to matching on the type of log entry generated. The full list of fields that can be used here is: .TP direction This option is used to match on log records generated for packets going in or out. .TP dstip
This option is used to match against the destination address associated with the packet being logged. A "/mask" must be given and given in CIDR notation (/0-/32) so to specify host 192.2.2.1, 192.2.2.1/32 must be given. .TP dstport This option is used to match against the destination port in log entries. A number must be given, symbolic names (such as those from /etc/services) are not recognised by the parser. .TP every This option is used to regulate how often an \fBipmon.conf\fR entry is actioned in response to an otherwise matching log record from the kernel. .TP group .TP interface This option is used to match against the network interface name associated with the action causing the logging to happen. In general this will be the network interface where the packet is seen by IPFilter. .TP logtag This option is used to match against tags set by ipf rules in \fBipf.conf\fR. These tags are set with "set-tag(log=100)" appended to filter rules. .TP nattag This option is used to match against tags set by NAT rules in \fBipnat.conf\fR. .TP protocol This option is used to match against the IP protocol field in the packet being logged. .TP result This option is used to match against the result of packet matching in the kernel. If a packet is logged, using a \fBlog\fR rule in \fBipf.conf\fR then it will match "log" here. The "nomatch" option is for use with matching log records generated for all packets as the default. .TP rule This option is used to match against the \fInumber\fR of the rule causing the record to be generated. The \fInumber\fR of a rule can be observed using "ipfstat -ion". .TP srcip
This option is used to match against the source address associated with the packet being logged. A "/mask" must be given and given in CIDR notation (/0-/32) so to specify host 192.2.2.1, 192.2.2.1/32 must be given. .TP srcport This option is used to match against the source port in log entries. A number must be given, symbolic names (such as those from /etc/services) are not recognised by the parser. .TP type The format for files accepted by ipmon is described by the following grammar: .B NOTE: At present, only IPv4 matching is available for source/destination address matching. .SH SYNTAX - ACTIONS The list of actions supported is as follows: .TP save("file://") save("raw://") Write out the log record to the filename given. This file will be closed and reopened on receipt of a SIGHUP. If the \fIraw\fP target is used, binary log data, as read from the kernel, is written out rather than a text log record. The filename should be an absolute target, including the root directory. Thus, saving to /var/log/ipmon.log would be, as an example, save("file:///var/log/ipmon.log"). .TP syslog(".") syslog(".") syslog(".") To log a text record via syslog, the \fBsyslog\fP action word is used. The facility used by default is determined at first by the default compiled into \fBipmon\fP (usually LOG_LOCAL0), which can be changed via the command line (-L ) or in an \fBipf.conf\fP rule using the \fIlevel\fP option with logging. If the facility is specified here, it takes precedence over all other settings. The same applies to the syslog priority. By default, ipmon will determine a priority for the packet, depending on whether or not it has been blocked, passed, etc. It is possible to force the complete facility/priority value for each log entry or to choose to replace only one of them. .TP execute("") The .B execute action runs the specified command each time the log entry matches and feeds the log entry, as text, to the command being executed. The command string given is executed using /bin/sh. .TP nothing Literally, do nothing. Use this if you want to be verbose in your config file about doing nothing for a particular log record. .SH PLUGIN ACTIONS It is possible to configure .B ipmon to use externally supplied modules to save log entries with. These are added to .B ipmon using the .I load_action configuration line. The syntax of this line is: .nf load_action ; .fi .TP name is a short name for the action. It does not need to correspond to the name of the library file, but inside the library file, the functions .B destroy , .B parse and .B store must be present. .TP path specifies the path in the filesystem to the shared object that contains the implementation of the new action. After the new action has been declared using .I load_action it can then be used in any .I do statement. .SH EXAMPLES -.PP Some further examples are: .nf # # log everything to syslog local4, regardless # match { ; } do { syslog("local4."); }; # # keep a local copy of things packets to/from port 80 # match { srcport = 80; } do { save("file:///var/log/web"); }; match { dstport = 80; } do { save("file:///var/log/web"); }; # load_action local "/usr/lib/libmyaction.so"; match { dstip 127.0.0.1; } do { local("local options"); }; # .fi .SH MATCHING -.PP All entries of the rules present in the file are compared for matches - there is no first or last rule match. .SH FILES /dev/ipl .br /dev/ipf .br /dev/ipnat .br /dev/ipstate .br /etc/ipmon.conf .SH SEE ALSO ipmon(8), ipl(4) diff --git a/sbin/ipf/ipmon/ipmon.8 b/sbin/ipf/ipmon/ipmon.8 index cb6567e316b0..901d1a2a804e 100644 --- a/sbin/ipf/ipmon/ipmon.8 +++ b/sbin/ipf/ipmon/ipmon.8 @@ -1,195 +1,193 @@ .TH ipmon 8 .SH NAME ipmon \- monitors /dev/ipl for logged packets .SH SYNOPSIS .B ipmon [ .B \-abBDFhnpstvxX ] [ .B "\-B " ] [ .B "\-C " ] [ .B "\-N " ] [ .B "\-L " ] [ .B "\-o [NSI]" ] [ .B "\-O [NSI]" ] [ .B "\-P " ] [ .B "\-S " ] [ .B "\-f " ] [ .B ] .SH DESCRIPTION -.LP \fBipmon\fP opens \fB/dev/ipl\fP for reading and awaits data to be saved from the packet filter. The binary data read from the device is reprinted in human readable form, however, IP#'s are not mapped back to hostnames, nor are ports mapped back to service names. The output goes to standard output by default or a filename, if given on the command line. Should the \fB\-s\fP option be used, output is instead sent to \fBsyslogd(8)\fP. Messages sent via syslog have the day, month and year removed from the message, but the time (including microseconds), as recorded in the log, is still included. .LP Messages generated by ipmon consist of whitespace separated fields. Fields common to all messages are: .LP 1. The date of packet receipt. This is suppressed when the message is sent to syslog. .LP 2. The time of packet receipt. This is in the form HH:MM:SS.F, for hours, minutes seconds, and fractions of a second (which can be several digits long). .LP 3. The name of the interface the packet was processed on, e.g., \fBwe1\fP. .LP 4. The group and rule number of the rule, e.g., \fB@0:17\fP. These can be viewed with \fBipfstat -n\fP. .LP 5. The action: \fBp\fP for passed, \fBb\fP for blocked, \fB\fP for a short packet, \fBn\fP did not match any rules or \fBL\fP for a log rule. .LP 6. The addresses. This is actually three fields: the source address and port (separated by a comma), the \fB->\fP symbol, and the destination address and port. E.g.: \fB209.53.17.22,80 -> 198.73.220.17,1722\fP. .LP 7. \fBPR\fP followed by the protocol name or number, e.g., \fBPR tcp\fP. .LP 8. \fBlen\fP followed by the header length and total length of the packet, e.g., \fBlen 20 40\fP. .LP If the packet is a TCP packet, there will be an additional field starting with a hyphen followed by letters corresponding to any flags that were set. See the ipf.conf manual page for a list of letters and their flags. .LP If the packet is an ICMP packet, there will be two fields at the end, the first always being `icmp', and the next being the ICMP message and submessage type, separated by a slash, e.g., \fBicmp 3/3\fP for a port unreachable message. .LP In order for \fBipmon\fP to properly work, the kernel option \fBIPFILTER_LOG\fP must be turned on in your kernel. Please see \fBoptions(4)\fP for more details. .LP \fBipmon\fP reopens its log file(s) and rereads its configuration file when it receives a SIGHUP signal. .SH OPTIONS .TP .B \-a Open all of the device logfiles for reading log entries from. All entries are displayed to the same output 'device' (stderr or syslog). .TP .B \-b For rules which log the body of a packet, generate hex output representing the packet contents after the headers. .TP .B \-B Enable logging of the raw, unformatted binary data to the specified \fI\fP file. This can be read, later, using \fBipmon\fP with the \fB-f\fP option. .TP .B \-C This option specifies a file to be used to specify optional extra actions when it sees specific log entries from the kernel. .TP .B \-D Cause ipmon to turn itself into a daemon. Using subshells or backgrounding of ipmon is not required to turn it into an orphan so it can run indefinitely. .TP .B "\-f " specify an alternative device/file from which to read the log information for normal IP Filter log records. .TP .B \-F Flush the current packet log buffer. The number of bytes flushed is displayed, even should the result be zero. .TP .B \-L Using this option allows you to change the default syslog facility that ipmon uses for syslog messages. The default is local0. .TP .B \-n IP addresses and port numbers will be mapped, where possible, back into hostnames and service names. .TP .B "\-N " Set the logfile to be opened for reading NAT log records from to . .TP .B \-o Specify which log files to actually read data from. N - NAT logfile, S - State logfile, I - normal IP Filter logfile. The \fB-a\fP option is equivalent to using \fB-o NSI\fP. .TP .B \-O Specify which log files you do not wish to read from. This is most sensibly used with the \fB-a\fP. Letters available as parameters to this are the same as for \fB-o\fP. .TP .B \-p Cause the port number in log messages to always be printed as a number and never attempt to look it up as from \fI/etc/services\fP, etc. .TP .B \-P Write the pid of the ipmon process to a file. By default this is \fI//etc/opt/ipf/ipmon.pid\fP (Solaris), \fI/var/run/ipmon.pid\fP (44BSD or later) or \fI/etc/ipmon.pid\fP for all others. .TP .B \-s Packet information read in will be sent through syslogd rather than saved to a file. The default facility when compiled and installed is \fBsecurity\fP. The following levels are used: .IP .B LOG_INFO \- packets logged using the "log" keyword as the action rather than pass or block. .IP .B LOG_NOTICE \- packets logged which are also passed .IP .B LOG_WARNING \- packets logged which are also blocked .IP .B LOG_ERR \- packets which have been logged and which can be considered "short". .TP .B "\-S " Set the logfile to be opened for reading state log records from to . .TP .B \-t read the input file/device in a manner akin to tail(1). .TP .B \-v show tcp window, ack and sequence fields. .TP .B \-x show the packet data in hex. .TP .B \-X show the log header record data in hex. .SH DIAGNOSTICS \fBipmon\fP expects data that it reads to be consistent with how it should be saved and will abort if it fails an assertion which detects an anomaly in the recorded data. .SH FILES /dev/ipl .br /dev/ipnat .br /dev/ipstate .br /etc/ipmon.conf .br /etc/services .SH SEE ALSO ipl(4), ipmon(5), ipf(8), ipfstat(8), ipnat(8) .SH BUGS -.PP If you find any, please send email to me at darrenr@pobox.com diff --git a/sbin/ipf/ipnat/ipnat.1 b/sbin/ipf/ipnat/ipnat.1 index f24141546171..0e41ccc42b2a 100644 --- a/sbin/ipf/ipnat/ipnat.1 +++ b/sbin/ipf/ipnat/ipnat.1 @@ -1,48 +1,47 @@ .TH IPNAT 1 .SH NAME ipnat \- user interface to the NAT .SH SYNOPSIS .B ipnat [ .B \-lnrsvCF ] .B \-f <\fIfilename\fP> .SH DESCRIPTION -.PP \fBipnat\fP opens the filename given (treating "\-" as stdin) and parses the file for a set of rules which are to be added or removed from the IP NAT. .PP Each rule processed by \fBipnat\fP is added to the kernels internal lists if there are no parsing problems. Rules are added to the end of the internal lists, matching the order in which they appear when given to \fBipnat\fP. .SH OPTIONS .TP .B \-C delete all entries in the current NAT rule listing (NAT rules) .TP .B \-F delete all active entries in the current NAT translation table (currently active NAT mappings) .TP .B \-l Show the list of current NAT table entry mappings. .TP .B \-n This flag (no-change) prevents \fBipf\fP from actually making any ioctl calls or doing anything which would alter the currently running kernel. .TP .B \-s Retrieve and display NAT statistics .TP .B \-r Remove matching NAT rules rather than add them to the internal lists .TP .B \-v Turn verbose mode on. Displays information relating to rule processing and active rules/table entries. .DT .SH FILES /dev/ipnat .SH SEE ALSO ipnat(5), ipf(8), ipfstat(8) diff --git a/sbin/ipf/ipnat/ipnat.4 b/sbin/ipf/ipnat/ipnat.4 index 2a866d4a8f19..d848378d8e98 100644 --- a/sbin/ipf/ipnat/ipnat.4 +++ b/sbin/ipf/ipnat/ipnat.4 @@ -1,96 +1,95 @@ .TH IPNAT 4 .SH NAME ipnat \- Network Address Translation kernel interface .SH SYNOPSIS #include .br #include .br #include .br #include .SH IOCTLS -.PP To add and delete rules to the NAT list, two 'basic' ioctls are provided for use. The ioctl's are called as: .LP .nf ioctl(fd, SIOCADNAT, struct ipnat **) ioctl(fd, SIOCRMNAT, struct ipnat **) ioctl(fd, SIOCGNATS, struct natstat **) ioctl(fd, SIOCGNATL, struct natlookup **) .fi .PP Unlike \fBipf(4)\fP, there is only a single list supported by the kernel NAT interface. An inactive list which can be swapped to is not currently supported. These ioctl's are implemented as being routing ioctls and thus the same rules for the various routing ioctls and the file descriptor are employed, mainly being that the fd must be that of the device associated with the module (i.e., /dev/ipl). .PP The structure used with the NAT interface is described below: .LP .nf typedef struct ipnat { struct ipnat *in_next; void *in_ifp; u_short in_flags; u_short in_pnext; u_short in_port[2]; struct in_addr in_in[2]; struct in_addr in_out[2]; struct in_addr in_nextip; int in_space; int in_redir; /* 0 if it's a mapping, 1 if it's a hard redir */ char in_ifname[IFNAMSIZ]; } ipnat_t; #define in_pmin in_port[0] /* Also holds static redir port */ #define in_pmax in_port[1] #define in_nip in_nextip.s_addr #define in_inip in_in[0].s_addr #define in_inmsk in_in[1].s_addr #define in_outip in_out[0].s_addr #define in_outmsk in_out[1].s_addr .fi .PP Recognised values for in_redir: .LP .nf #define NAT_MAP 0 #define NAT_REDIRECT 1 .fi .LP \fBNAT statistics\fP Statistics on the number of packets mapped, going in and out are kept, the number of times a new entry is added and deleted (through expiration) to the NAT table and the current usage level of the NAT table. .PP Pointers to the NAT table inside the kernel, as well as to the top of the internal NAT lists constructed with the \fBSIOCADNAT\fP ioctls. The table itself is a hash table of size NAT_SIZE (default size is 367). .PP To retrieve the statistics, the \fBSIOCGNATS\fP ioctl must be used, with the appropriate structure passed by reference, as follows: .nf ioctl(fd, SIOCGNATS, struct natstat *) typedef struct natstat { u_long ns_mapped[2]; u_long ns_added; u_long ns_expire; u_long ns_inuse; nat_t ***ns_table; ipnat_t *ns_list; } natstat_t; .fi .SH BUGS It would be nice if there were more flexibility when adding and deleting filter rules. .SH FILES /dev/ipnat .SH SEE ALSO ipf(4), ipnat(5), ipf(8), ipnat(8), ipfstat(8) diff --git a/sbin/ipf/ipnat/ipnat.5 b/sbin/ipf/ipnat/ipnat.5 index b01892f9749d..2b391f119450 100644 --- a/sbin/ipf/ipnat/ipnat.5 +++ b/sbin/ipf/ipnat/ipnat.5 @@ -1,727 +1,718 @@ .\" .TH IPNAT 5 .SH NAME ipnat, ipnat.conf \- IPFilter NAT file format .SH DESCRIPTION -.PP The .B ipnat.conf file is used to specify rules for the Network Address Translation (NAT) component of IPFilter. To load rules specified in the .B ipnat.conf file, the .B ipnat(8) program is used. .PP For standard NAT functionality, a rule should start with \fBmap\fP and then proceeds to specify the interface for which outgoing packets will have their source address rewritten. Following this it is expected that the old source address, and optionally port number, will be specified. .PP In general, all NAT rules conform to the following layout: the first word indicates what type of NAT rule is present, this is followed by some stanzas to match a packet, followed by a "->" and this is then followed by several more stanzas describing the new data to be put in the packet. .PP In this text and in others, use of the term "left hand side" (LHS) when talking about a NAT rule refers to text that appears before the "->" and the "right hand side" (RHS) for text that appears after it. In essence, the LHS is the packet matching and the RHS is the new data to be used. .SH VARIABLES -.PP This configuration file, like all others used with IPFilter, supports the use of variable substitution throughout the text. .nf nif="ppp0"; map $nif 0/0 -> 0/32 .fi .PP would become .nf map ppp0 0/0 -> 0/32 .fi .PP Variables can be used recursively, such as 'foo="$bar baz";', so long as $bar exists when the parser reaches the assignment for foo. .PP See .B ipnat(8) for instructions on how to define variables to be used from a shell environment. .SH OUTBOUND SOURCE TRANSLATION (map'ing) Changing the source address of a packet is traditionally performed using .B map rules. Both the source address and optionally port number can be changed according to various controls. .PP To start out with, a common rule used is of the form: .nf map le0 0/0 -> 0/32 .fi .PP Here we're saying change the source address of all packets going out of le0 (the address/mask pair of 0/0 matching all packets) to that of the interface le0 (0/32 is a synonym for the interface's own address at the current point in time.) If we wanted to pass the packet through with no change in address, we would write it as: .nf map le0 0/0 -> 0/0 .fi .PP If we only want to change a portion of our internal network and to a different address that is routed back through this host, we might do: .nf map le0 10.1.1.0/24 -> 192.168.55.3/32 .fi .PP In some instances, we may have an entire subnet to map internal addresses out onto, in which case we can express the translation as this: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 .fi .PP IPFilter will cycle through each of the 256 addresses in the 192.168.55.0/24 address space to ensure that they all get used. .PP Of course this poses a problem for TCP and UDP, with many connections made, each with its own port number pair. If we're unlucky, translations can be dropped because the new address/port pair mapping already exists. To mitigate this problem, we add in port translation or port mapping: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp auto .fi .PP In this instance, the word "auto" tells IPFilter to calculate a private range of port numbers for each address on the LHS to use without fear of them being trampled by others. This can lead to problems if there are connections being generated more quickly than IPFilter can expire them. In this instance, and if we want to get away from a private range of port numbers, we can say: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp 5000:65000 .fi .PP And now each connection through le0 will add to the enumeration of the port number space 5000-65000 as well as the IP address subnet of 192.168.55.0/24. .PP If the new addresses to be used are in a consecutive range, rather than a complete subnet, we can express this as: .nf map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.249 portmap tcp/udp 5000:65000 .fi .PP This tells IPFilter that it has a range of 240 IP address to use, from 192.168.55.10 to 192.168.55.249, inclusive. .PP If there were several ranges of addresses for use, we can use each one in a round-robin fashion as followed: .nf map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.29 portmap tcp/udp 5000:65000 round-robin map le0 10.0.0.0/8 -> range 192.168.55.40-192.168.55.49 portmap tcp/udp 5000:65000 round-robin .fi .PP To specify translation rules that impact a specific IP protocol, the protocol name or number is appended to the rule like this: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 tcp/udp map le0 10.0.0.0/8 -> 192.168.55.1/32 icmp map le0 10.0.0.0/8 -> 192.168.55.2/32 gre .fi .PP For TCP connections exiting a connection such as PPPoE where the MTU is slightly smaller than normal ethernet, it can be useful to reduce the Maximum Segment Size (MSS) offered by the internal machines to match, reducing the liklihood that the either end will attempt to send packets that are too big and result in fragmentation. This is achieved using the .B mssclamp option with TCP .B map rules like this: .nf map pppoe0 0/0 -> 0/32 mssclamp 1400 tcp .fi .PP For ICMP packets, we can map the ICMP id space in query packets: .nf map le0 10.0.0.0/8 -> 192.168.55.1/32 icmpidmap icmp 1000:20000 .fi .PP If we wish to be more specific about our initial matching criteria on the LHS, we can expand to using a syntax more similar to that in .B ipf.conf(5) : .nf map le0 from 10.0.0.0/8 to 26.0.0.0/8 -> 192.168.55.1 map le0 from 10.0.0.0/8 port > 1024 to 26.0.0.0/8 -> 192.168.55.2 portmap 5000:9999 tcp/udp map le0 from 10.0.0.0/8 ! to 26.0.0.0/8 -> 192.168.55.3 portmap 5000:9999 tcp/udp .fi .TP .B NOTE: negation matching with source addresses is .B NOT possible with .B map / .B map-block rules. .PP The NAT code has builtin default timeouts for TCP, UDP, ICMP and another for all other protocols. In general, the timeout for an entry to be deleted shrinks once a reply packet has been seen (excluding TCP.) If you wish to specify your own timeouts, this can be achieved either by setting one timeout for both directions: .nf map le0 0/0 -> 0/32 gre age 30 .fi .PP or setting a different timeout for the reply: .nf map le0 from any to any port = 53 -> 0/32 age 60/10 udp .fi .PP A pressing problem that many people encounter when using NAT is that the address protocol can be embedded inside an application's communication. To address this problem, IPFilter provides a number of built-in proxies for the more common trouble makers, such as FTP. These proxies can be used as follows: .nf map le0 0/0 -> 0/32 proxy port 21 ftp/tcp .fi .PP In this rule, the word "proxy" tells us that we want to connect up this translation with an internal proxy. The "port 21" is an extra restriction that requires the destination port number to be 21 if this rule is to be activated. The word "ftp" is the proxy identifier that the kernel will try and resolve internally, "tcp" the protocol that packets must match. .PP See below for a list of proxies and their relative status. .PP To associate NAT rules with filtering rules, it is possible to set and match tags during either inbound or outbound processing. At present the tags for forwarded packets are not preserved by forwarding, so once the packet leaves IPFilter, the tag is forgotten. For .B map rules, we can match tags set by filter rules like this: .nf map le0 0/0 -> 0/32 proxy portmap 5000:5999 tag lan1 tcp .fi .PP This would be used with "pass out" rules that includes a stanza such as "set-tag (nat = lan1)". .PP If the interface in which packets are received is different from the interface on which packets are sent out, then the translation rule needs to be written to take this into account: .nf map hme0,le0 0/0 -> 0/32 .fi .PP Although this might seem counterintuitive, the interfaces when listed in rules for .B ipnat.conf are always in the .I inbound , .I outbound order. In this case, hme0 would be the return interface and le0 would be the outgoing interface. If you wish to allow return packets on any interface, the correct syntax to use would be: .nf map *,le0 0/0 -> 0/32 .fi .LP A special variant of .B map rules exists, called .B map-block. This command is intended for use when there is a large network to be mapped onto a smaller network, where the difference in netmasks is upto 14 bits difference in size. This is achieved by dividing the address space and port space up to ensure that each source address has its own private range of ports to use. For example, this rule: .nf map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto .fi .PP would result in 172.192.0.0/24 being mapped to 209.1.2.0/32 with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its own. As opposed to the above use of \fBmap\fP, if for some reason the user of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next IP address with the \fBmap\fP command. .SS Extended matching -.PP If it is desirable to match on both the source and destination of a packet before applying an address translation to it, this can be achieved by using the same from-to syntax as is used in \fBipf.conf\fP(5). What follows applies equally to the .B map rules discussed above and .B rdr rules discussed below. A simple example is as follows: .nf map bge0 from 10.1.0.0/16 to 192.168.1.0/24 -> 172.12.1.4 .fi .PP This would only match packets that are coming from hosts that have a source address matching 10.1.0.0/16 and a destination matching 192.168.1.0/24. This can be expanded upon with ports for TCP like this: .nf rdr bge0 from 10.1.0.0/16 to any port = 25 -> 127.0.0.1 port 2501 tcp .fi .PP Where only TCP packets from 10.1.0.0/16 to port 25 will be redirected to port 2501. .PP As with \fBipf.conf\fR(5), if we have a large set of networks or addresses that we would like to match up with then we can define a pool using \fBippool\fR(8) in \fBippool.conf\fR(5) and then refer to it in an \fBipnat\fR rule like this: .nf map bge0 from pool/100 to any port = 25 -> 127.0.0.1 port 2501 tcp .fi .TP .B NOTE: In this situation, the rule is considered to have a netmask of "0" and thus is looked at last, after any rules with /16's or /24's in them, .I even if the defined pool only has /24's or /32's. Pools may also be used .I wherever the from-to syntax in \fBipnat.conf\fR(5) is allowed. .SH INBOUND DESTINATION TRANSLATION (redirection) -.PP Redirection of packets is used to change the destination fields in a packet and is supported for packets that are moving \fIin\fP on a network interface. While the same general syntax for .B map rules is supported, there are differences and limitations. .PP Firstly, by default all redirection rules target a single IP address, not a network or range of network addresses, so a rule written like this: .nf rdr le0 0/0 -> 192.168.1.0 .fi .PP Will not spread packets across all 256 IP addresses in that class C network. If you were to try a rule like this: .nf rdr le0 0/0 -> 192.168.1.0/24 .fi .PP then you will receive a parsing error. .PP The from-to source-destination matching used with .B map rules can be used with rdr rules, along with negation, however the restriction moves - only a source address match can be negated: .nf rdr le0 from 1.1.0.0/16 to any -> 192.168.1.3 rdr le0 ! from 1.1.0.0/16 to any -> 192.168.1.4 .fi .PP If there is a consecutive set of addresses you wish to spread the packets over, then this can be done in one of two ways, the word "range" optional to preserve: .nf rdr le0 0/0 -> 192.168.1.1 - 192.168.1.5 rdr le0 0/0 -> range 192.168.1.1 - 192.168.1.5 .fi .PP If there are only two addresses to split the packets across, the recommended method is to use a comma (",") like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 .fi .PP If there is a large group of destination addresses that are somewhat disjoint in nature, we can cycle through them using a .B round-robin technique like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 round-robin rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin rdr le0 0/0 -> 192.168.1.9 round-robin .fi .PP If there are a large number of redirect rules and hosts being targeted then it may be desirable to have all those from a single source address be targeted at the same destination address. To achieve this, the word .B sticky is appended to the rule like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 sticky rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin sticky rdr le0 0/0 -> 192.168.1.9 round-robin sticky .fi .PP The .B sticky feature can only be combined with .B round-robin and the use of a comma. .PP For TCP and UDP packets, it is possible to both match on the destination port number and to modify it. For example, to change the destination port from 80 to 3128, we would use a rule like this: .nf rdr de0 0/0 port 80 -> 127.0.0.1 port 3128 tcp .fi .PP If a range of ports is given on the LHS and a single port is given on the RHS, the entire range of ports is moved. For example, if we had this: .nf rdr le0 0/0 port 80-88 -> 127.0.0.1 port 3128 tcp .fi .PP then port 80 would become 3128, port 81 would become 3129, etc. If we want to redirect a number of different pots to just a single port, an equals sign ("=") is placed before the port number on the RHS like this: .nf rdr le0 0/0 port 80-88 -> 127.0.0.1 port = 3128 tcp .fi .PP In this case, port 80 goes to 3128, port 81 to 3128, etc. .PP As with .B map rules, it is possible to manually set a timeout using the .B age option, like this: .nf rdr le0 0/0 port 53 -> 127.0.0.1 port 10053 udp age 5/5 .fi .PP The use of proxies is not restricted to .B map rules and outbound sessions. Proxies can also be used with redirect rules, although the syntax is slightly different: .nf rdr ge0 0/0 port 21 -> 127.0.0.1 port 21 tcp proxy ftp .fi .PP For .B rdr rules, the interfaces supplied are in the same order as .B map rules - input first, then output. In situations where the outgoing interface is not certain, it is also possible to use a wildcard ("*") to effect a match on any interface. .nf rdr le0,* 0/0 -> 192.168.1.0 .fi .PP A single rule, with as many options set as possible would look something like this: .nf rdr le0,ppp0 9.8.7.6/32 port 80 -> 1.1.1.1,1.1.1.2 port 80 tcp round-robin frag age 40/40 sticky mssclamp 1000 tag tagged .fi .SH REWRITING SOURCE AND DESTINATION -.PP Whilst the above two commands provide a lot of flexibility in changing addressing fields in packets, often it can be of benefit to translate \fIboth\fP source \fBand\fR destination at the same time or to change the source address on input or the destination address on output. Doing all of these things can be accomplished using .B rewrite NAT rules. .PP A .B rewrite rule requires the same level of packet matching as before, protocol and source/destination information but in addition allows either .B in or .B out to be specified like this: .nf rewrite in on ppp0 proto tcp from any to any port = 80 -> src 0/0 dst 127.0.0.1,3128; rewrite out on ppp0 from any to any -> src 0/32 dst 10.1.1.0/24; .fi .PP On the RHS we can specify both new source and destination information to place into the packet being sent out. As with other rules used in \fBipnat.conf\fR, there are shortcuts syntaxes available to use the original address information (\fB0/0\fR) and the address associated with the network interface (\fB0/32\fR.) For TCP and UDP, both address and port information can be changed. At present it is only possible to specify either a range of port numbers to be used (\fBX-Y\fR) or a single port number (\fB= X\fR) as follows: .nf rewrite in on le0 proto tcp from any to any port = 80 -> src 0/0,2000-20000 dst 127.0.0.1,port = 3128; .fi .PP There are four fields that are stepped through in enumerating the number space available for creating a new destination: .LP source address .LP source port .LP destination address .LP destination port .PP If one of these happens to be a static then it will be skipped and the next one incremented. As an example: .nf rewrite out on le0 proto tcp from any to any port = 80 -> src 1.0.0.0/8,5000-5999 dst 2.0.0.0/24,6000-6999; .fi .PP The translated packets would be: .LP 1st src=1.0.0.1,5000 dst=2.0.0.1,6000 .LP 2nd src=1.0.0.2,5000 dst=2.0.0.1,6000 .LP 3rd src=1.0.0.2,5001 dst=2.0.0.1,6000 .LP 4th src=1.0.0.2,5001 dst=2.0.0.2,6000 .LP 5th src=1.0.0.2,5001 dst=2.0.0.2,6001 .LP 6th src=1.0.0.3,5001 dst=2.0.0.2,6001 .PP and so on. .PP As with .B map rules, it is possible to specify a range of addresses by including the word \fIrange\fR before the addresses: .nf rewrite from any to any port = 80 -> src 1.1.2.3 - 1.1.2.6 dst 2.2.3.4 - 2.2.3.6; .fi .SH DIVERTING PACKETS -.PP If you'd like to send packets to a UDP socket rather than just another computer to be decapsulated, this can be achieved using a .B divert rule. .PP Divert rules can be used with both inbound and outbound packet matching however the rule .B must specify host addresses for the outer packet, not ranges of addresses or netmasks, just single addresses. Additionally the syntax must supply required information for UDP. An example of what a divert rule looks ike is as follows: .nf divert in on le0 proto udp from any to any port = 53 -> src 192.1.1.1,54 dst 192.168.1.22.1,5300; .fi .PP On the LHS is a normal set of matching capabilities but on the RHS it is a requirement to specify both the source and destination addresses and ports. .PP As this feature is intended to be used with targeting packets at sockets and not IPFilter running on other systems, there is no rule provided to \fIundivert\fR packets. .TP .B NOTE: Diverted packets \fImay\fP be fragmented if the addition of the encapsulating IP header plus UDP header causes the packet to exceed the size allowed by the outbound network interface. At present it is not possible to cause Path MTU discovery to happen as this feature is intended to be transparent to both endpoints. .B Path MTU Discovery If Path MTU discovery is being used and the "do not fragment" flag is set in packets to be encapsulated, an ICMP error message will be sent back to the sender if the new packet would need to be fragmented. .SH COMMON OPTIONS This section deals with options that are available with all rules. .TP .B purge When the purge keyword is added to the end of a NAT rule, it will cause all of the active NAT sessions to be removed when the rule is removed as an individual operation. If all of the NAT rules are flushed out, it is expected that the operator will similarly flush the NAT table and thus NAT sessions are not removed when the NAT rules are flushed out. .SH RULE ORDERING -.PP .B NOTE: Rules in .B ipnat.conf are read in sequentially as listed and loaded into the kernel in this fashion .B BUT packet matching is done on \fBnetmask\fR, going from 32 down to 0. If a rule uses .B pool or .B hash to reference a set of addresses or networks, the netmask value for these fields is considered to be "0". So if your .B ipnat.conf has the following rules: .nf rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp .fi .PP then the rule with 192.2.2.1 will match \fBfirst\fR, regardless of where it appears in the ordering of the above rules. In fact, the order in which they would be used to match a packet is: .nf rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp .fi .PP where the first line is actually a /32. .PP If your .B ipnat.conf file has entries with matching target fields (source address for .B map rules and destination address for .B rdr rules), then the ordering in the .B ipnat.conf file does matter. So if you had the following: .nf rdr le0 from 1.1.0.0/16 to 192.2.2.1 port 80 -> 127.0.0.1 3129 tcp rdr le0 from 1.1.1.0/24 to 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp .fi .PP Then no packets will match the 2nd rule, they'll all match the first. .SH IPv6 -.PP In all of the examples above, where an IPv4 address is present, an IPv6 address can also be used. All rules must use either IPv4 addresses with both halves of the NAT rule or IPv6 addresses for both halves. Mixing IPv6 addresses with IPv4 addresses, in a single rule, will result in an error. .PP For shorthand notations such as "0/32", the equivalent for IPv6 is "0/128". IPFilter will treat any netmask greater than 32 as an implicit direction that the address should be IPv6, not IPv4. To be unambiguous with 0/0, for IPv6 use ::0/0. .SH KERNEL PROXIES -.PP IP Filter comes with a few, simple, proxies built into the code that is loaded into the kernel to allow secondary channels to be opened without forcing the packets through a user program. The current state of the proxies is listed below, as one of three states: .HP Aging - protocol is roughly understood from the time at which the proxy was written but it is not well tested or maintained; .HP Developmental - basic functionality exists, works most of the time but may be problematic in extended real use; .HP Experimental - rough support for the protocol at best, may or may not work as testing has been at best sporadic, possible large scale changes to the code in order to properly support the protocol. .HP Mature - well tested, protocol is properly understood by the proxy; .PP The currently compiled in proxy list is as follows: .TP FTP - Mature (map ... proxy port ftp ftp/tcp) .TP IRC - Experimental (proxy port 6667 irc/tcp) .TP rpcbind - Experimental .TP PPTP - Experimental .TP H.323 - Experimental (map ... proxy port 1720 h323/tcp) .TP Real Audio (PNA) - Aging .TP DNS - Developmental (map ... proxy port 53 dns/udp { block .cnn.com; }) .TP IPsec - Developmental (map ... proxy port 500 ipsec/tcp) .TP netbios - Experimental .TP R-command - Mature (map ... proxy port shell rcmd/tcp) .SH KERNEL PROXIES .SH FILES /dev/ipnat .br /etc/protocols .br /etc/services .br /etc/hosts .SH SEE ALSO ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8) diff --git a/sbin/ipf/ipnat/ipnat.8 b/sbin/ipf/ipnat/ipnat.8 index 2ef14a971831..b3893f117709 100644 --- a/sbin/ipf/ipnat/ipnat.8 +++ b/sbin/ipf/ipnat/ipnat.8 @@ -1,75 +1,74 @@ .\" .TH IPNAT 8 .SH NAME ipnat \- user interface to the NAT subsystem .SH SYNOPSIS .B ipnat [ .B \-dhlnrsvCF ] [ .B \-M core ] [ .B \-N system ] .B \-f <\fIfilename\fP> .SH DESCRIPTION -.PP \fBipnat\fP opens the filename given (treating "\-" as stdin) and parses the file for a set of rules which are to be added or removed from the IP NAT. .PP Each rule processed by \fBipnat\fP is added to the kernels internal lists if there are no parsing problems. Rules are added to the end of the internal lists, matching the order in which they appear when given to \fBipnat\fP. .PP Note that if \fBipf(8)\fP is not enabled when NAT is configured, it will be enabled automatically, as the same kernel facilities are used for NAT functionality. In addition, packet forwarding must be enabled. .SH OPTIONS .TP .B \-C delete all entries in the current NAT rule listing (NAT rules) .TP .B \-d Enable printing of some extra debugging information. .TP .B \-F delete all active entries in the current NAT translation table (currently active NAT mappings) .TP .B \-h Print number of hits for each MAP/Redirect filter. .TP .B \-l Show the list of current NAT table entry mappings. .TP .B \-n This flag (no-change) prevents \fBipf\fP from actually making any ioctl calls or doing anything which would alter the currently running kernel. .TP .B \-p This flag is used with the \fB-r\fP flag to cause any active NAT sessions that were created by the rules being removed and that are currently active to also be removed. .TP .B \-r Remove matching NAT rules rather than add them to the internal lists. .TP .B \-s Retrieve and display NAT statistics. .TP .B \-v Turn verbose mode on. Displays information relating to rule processing and active rules/table entries. .DT .SH FILES /dev/ipnat .br /usr/share/examples/ipfilter Directory with examples. .SH SEE ALSO ipnat(5), ipf(8), ipfstat(8) diff --git a/sbin/ipf/ippool/ippool.5 b/sbin/ipf/ippool/ippool.5 index 3b5c4d0f2bf6..d631de355a0e 100644 --- a/sbin/ipf/ippool/ippool.5 +++ b/sbin/ipf/ippool/ippool.5 @@ -1,319 +1,313 @@ .\" .TH IPPOOL 5 .SH NAME ippool, ippool.conf \- IP Pool file format .SH DESCRIPTION The file ippool.conf is used with ippool(8) to configure address pools for use with ipnat(8) and ipf(8). .PP There are four different types of address pools that can be configured through ippool.conf. The various types are presented below with a brief description of how they are used: .HP dstlist .IP destination list - is a collection of IP addresses with an optional network interface name that can be used with either redirect (rdr) rules in ipnat.conf(5) or as the destination in ipf.conf(5) for policy based routing. .HP group-map .IP group maps - support the srcgrpmap and dstgrpmap call functions in ipf.conf(5) by providing a list of addresses or networks rule group numbers to start processing them with. .HP hash .IP hash tables - provide the means for performing a very efficient lookup address or network when there is expected to be only one exact match. These are best used with more static sets of addresses so they can be sized optimally. .HP pool .IP address pools - are an alternative to hash tables that can perform just as well in most circumstances. In addition, the address pools allow for heirarchical matching, so it is possible to define a subnet as matching but then exclude specific addresses from it. .SS Evolving Configuration -.PP Over time the configuration syntax used by ippool.conf(5) has evolved. Originally the syntax used was more verbose about what a particular value was being used for, for example: .PP .nf table role = ipf type = tree number = 100 { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; }; .fi .PP This is rather long winded. The evolution of the configuration syntax has also replaced the use of numbers with names, although numbers can still be used as can be seen here: .PP .nf pool ipf/tree (name "100";) { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; }; .fi .PP Both of the above examples produce the same configuration in the kernel for use with ipf.conf(5). .PP Newer options for use in ippool.conf(5) will only be offered in the new configuration syntax and all output using "ippool -l" will also be in the new configuration syntax. .SS IPFilter devices and pools -.PP To cater to different administration styles, ipool.conf(5) allows you to tie a pool to a specific role in IPFilter. The recognised role names are: .HP ipf .IP pools defined for role "ipf" are available for use with all rules that are found in ipf.conf(5) except for auth rules. .HP nat .IP pools defined for role "nat" are available for use with all rules that are found in ipnat.conf(5). .HP auth .IP pools defined for role "auth" are available only for use with "auth" rules that are found in ipf.conf(5) .HP all .IP pools that are defined for the "all" role are available to all types of rules, be they NAT rules in ipnat.conf(5) or firewall rules in ipf.conf(5). .SH Address Pools -.PP An address pool can be used in ipf.conf(5) and ipnat.conf(5) for matching the source or destination address of packets. They can be referred to either by name or number and can hold an arbitrary number of address patterns to match. .PP An address pool is considered to be a "tree type". In the older configuration style, it was necessary to have "type=tree" in ippool.conf(5). In the new style configuration, it follows the IPFilter device with which the pool is being configured. Now it is the default if left out. .PP For convenience, both IPv4 and IPv6 addresses can be stored in the same address pool. It should go without saying that either type of packet can only ever match an entry in a pool that is of the same address family. .PP The address pool searches the list of addresses configured for the best match. The "best match" is considered to be the match that has the highest number of bits set in the mask. Thus if both 2.2.0.0/16 and 2.2.2.0/24 are present in an address pool, the address 2.2.2.1 will match 2.2.2.0/24 and 2.2.1.1 will match 2.2.0.0/16. The reason for this is to allow exceptions to be added through the use of negative matching. In the following example, the pool contains "2.2.0.0/16" and "!2.2.2.0/24", meaning that all packets that match 2.2.0.0/16, except those that match 2.2.2.0/24, will be considered as a match for this pool. .PP table role = ipf type = tree number = 100 { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24; ef00::5/128; }; .PP For the sake of clarity and to aid in managing large numbers of addresses inside address pools, it is possible to specify a location to load the addresses from. To do this simply use a "file://" URL where you would specify an actual IP address. .PP .nf pool ipf/tree (name rfc1918;) { file:///etc/ipf/rfc1918; }; .fi .PP The contents of the file might look something like this: .PP .nf # RFC 1918 networks 10.0.0.0/8 !127.0.0.0/8 172.16.0.0/12 192.168.0.0/24 .fi .PP In this example, the inclusion of the line "!127.0.0.0/8" is, strictly speaking not correct and serves only as an example to show that negative matching is also supported in this file. .PP Another format that ippool(8) recognises for input from a file is that from whois servers. In the following example, output from a query to a WHOIS server for information about which networks are associated with the name "microsoft" has been saved in a file named "ms-networks". There is no need to modify the output from the whois server, so using either the whois command or dumping data directly from it over a TCP connection works perfectly file as input. .PP .nf pool ipf/tree (name microsoft;) { whois file "/etc/ipf/ms-networks"; }; .fi .PP And to then block all packets to/from networks defined in that file, a rule like this might be used: .PP .nf block in from pool/microsoft to any .fi .PP Note that there are limitations on the output returned by whois servers so be aware that their output may not be 100% perfect for your goal. .SH Destination Lists -.PP Destination lists are provided for use primarily with NAT redirect rules (rdr). Their purpose is to allow more sophisticated methods of selecting which host to send traffic to next than the simple round-robin technique that is present with with "round-robin" rules in ipnat.conf(5). .PP When building a list of hosts to use as a redirection list, it is necessary to list each host to be used explicitly. Expressing a collection of hosts as a range or a subnet is not supported. With each address it is also possible to specify a network interface name. The network interface name is ignored by NAT when using destination lists. The network itnerface name is currently only used with policy based routing (use of "to"/"dup-to" in ipf.conf(5)). .PP Unlike the other directives that can be expressed in this file, destination lists must be written using the new configuration syntax. Each destination list must have a name associated with it and a next hop selection policy. Some policies have further options. The currently available selection policies are: .HP round-robin .IP steps through the list of hosts configured with the destination list one by one .HP random .IP the next hop is chosen by random selection from the list available .HP src-hash .IP a hash is made of the source address components of the packet (address and port number) and this is used to select which next hop address is used .HP dst-hash .IP a hash is made of the destination address components of the packet (address and port number) and this is used to select which next hop address is used .HP hash .IP a hash is made of all the address components in the packet (addresses and port numbers) and this is used to select which next hop address is used .HP weighted .IP selecting a weighted policy for destination selection needs further clarification as to what type of weighted selection will be used. The sub-options to a weighted policy are: .RS .HP connection .IP the host that has received the least number of connections is selected to be the next hop. When all hosts have the same connection count, the last one used will be the next address selected. .RE .PP The first example here shows 4 destinations that are used with a round-robin selection policy. .PP .nf pool nat/dstlist (name servers; policy round-robin;) { 1.1.1.2; 1.1.1.4; 1.1.1.5; 1.1.1.9; }; .fi .PP In the following example, the destination is chosen by whichever has had the least number of connections. By placing the interface name with each address and saying "all/dstlist", the destination list can be used with both ipnat.conf(5) and ipf.conf(5). .PP .nf pool all/dstlist (name servers; policy weighted connection;) { bge0:1.1.1.2; bge0:1.1.1.4; bge1:1.1.1.5; bge1:1.1.1.9; }; .fi .SH Group maps -.PP Group maps are provided to allow more efficient processing of packets where there are a larger number of subnets and groups of rules for those subnets. Group maps are used with "call" rules in ipf.conf(5) that use the "srcgrpmap" and "dstgrpmap" functions. .PP A group map declaration must mention which group is the default group for all matching addresses to be applied to. Then inside the list of addresses and networks for the group, each one may optionally have a group number associated with it. A simple example like this, where the first two entries would map to group 2020 but 5.0.0.0/8 sends rule processing to group 2040. .PP .nf group-map out role = ipf number = 2010 group = 2020 { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; }; .fi .PP An example that outlines the real purpose of group maps is below, where each one of the 12 subnets is mapped to a different group number. This might be because each subnet has its own policy and rather than write a list of twelve rules in ipf.conf(5) that match the subnet and branch off with a head statement, a single rule can be used with this group map to achieve the same result. .PP .nf group-map ( name "2010"; in; ) { 192.168.1.0/24, group = 10010; 192.168.2.0/24, group = 10020; 192.168.3.0/24, group = 10030; 192.168.4.0/24, group = 10040; 192.168.5.0/24, group = 10050; 192.168.6.0/24, group = 10060; 192.168.7.0/24, group = 10070; 192.168.8.0/24, group = 10080; 192.168.9.0/24, group = 10090; 192.168.10.0/24, group = 10100; 192.168.11.0/24, group = 10110; 192.168.12.0/24, group = 10120; }; .fi .PP The limitation with group maps is that only the source address or the destination address can be used to map the packet to the starting group, not both, in your ipf.conf(5) file. .SH Hash Tables -.PP The hash table is operationally similar to the address pool. It is used as a store for a collection of address to match on, saving the need to write a lengthy list of rules. As with address pools, searching will attempt to find the best match - an address specification with the largest contiguous netmask. .PP Hash tables are best used where the list of addresses, subnets and networks is relatively static, which is something of a contrast to the address pool that can work with either static or changing address list sizes. .PP Further work is still needed to have IPFilter correctly size and tune the hash table to optimise searching. The goal is to allow for small to medium sized tables to achieve close to O(1) for either a positive or negative match, in contrast to the address pool, which is O(logn). .PP The following two examples build the same table in the kernel, using the old configuration format (first) and the new one (second). .PP .nf table role=all type=hash name=servers size=5 { 1.1.1.2/32; 1.1.1.3/32; 11.23.44.66/32; }; pool all/hash (name servers; size 5;) { 1.1.1.2; 1.1.1.3; 11.23.44.66; }; .fi .SH FILES /dev/iplookup .br /etc/ippool.conf .br /etc/hosts .SH SEE ALSO ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8) diff --git a/sbin/ipf/ippool/ippool.8 b/sbin/ipf/ippool/ippool.8 index 1ff9911a87d8..c879c97b01dd 100644 --- a/sbin/ipf/ippool/ippool.8 +++ b/sbin/ipf/ippool/ippool.8 @@ -1,133 +1,132 @@ .\" .TH IPPOOL 8 .SH NAME ippool \- user interface to the IPFilter pools .SH SYNOPSIS .br .B ippool -a [-dnv] [-m ] [-o ] [-t ] [-T ttl] -i [/] .br .B ippool -A [-dnv] [-m ] [-o ] [-S ] -t .br .B ippool -f [-dnuvR] [-f ] [-t ] .br .B ippool -l [-dDv] [-m ] [-t ] [-o ] [-M ] [-N ] .br .B ippool -r [-dnv] [-m ] [-o ] [-t ] -i [/] .br .B ippool -R [-dnv] [-m ] [-o ] -t .br .B ippool -s [-dtv] .SH DESCRIPTION -.PP .B Ippool is used to manage information stored in the IP pools subsystem of IPFilter. Configuration file information may be parsed and loaded into the kernel, currently configured pools removed or changed as well as inspected. .PP The command line options used are broken into two sections: the global options and the instance specific options. .SH GLOBAL OPTIONS .TP .B \-d Toggle debugging of processing the configuration file. .TP .B \-n This flag (no-change) prevents .B ippool from actually making any ioctl calls or doing anything which would alter the currently running kernel. .TP .B \-v Turn verbose mode on. .SH COMMAND OPTIONS .TP .B -a Add a new data node to an existing pool in the kernel. .TP .B -A Add a new (empty) pool to the kernel. .TP .B -f Read in IP pool configuration information from the file and load it into the kernel. .TP .B -F Flush loaded pools from the kernel. .TP .B -l Display a list of pools currently loaded into the kernel. .TP .B -r Remove an existing data node from a pool in the kernel. .TP .B -R Remove an existing pool from within the kernel. .TP .B -s Display IP pool statistical information. .SH OPTIONS .TP .B -i [/] Sets the IP address for the operation being undertaken with an all-one's mask or, optionally, a specific netmask given in either the dotted-quad notation or a single integer. .TP .B -m Sets the pool name for the current operation. .TP .B -M Specify an alternative path to /dev/kmem to retrieve statistical information from. .TP .B -N Specify an alternative path to lookup symbol name information from when retrieving statistical information. .TP .B -o Sets the role with which this pool is to be used. Currently only .B ipf (the default) is accepted as arguments to this option. .TP .B -S Sets the hashing seed to the number specified. Only for use with .B hash type pools. .TP .B -t Sets the type of pool being defined. Must be one of .B tree, .B hash, .B group-map. .TP .B -T Sets the expiration of the node being added. The timeout is expressed as a number of seconds. .B tree, .B hash, .B group-map. .TP .B -u When parsing a configuration file, rather than load new pool data into the kernel, unload it. .TP .B -D When used in conjuction with -l, dump the ippool configuration to stdout in a format that can be subsequently used as input into ippool -f. .TP .SH FILES .br /dev/iplookup .br /etc/ippool.conf .SH SEE ALSO ippool(5), ipf(8), ipfstat(8) diff --git a/sbin/ipf/ipscan/ipscan.5 b/sbin/ipf/ipscan/ipscan.5 index 72b3f92a25a0..76738b607080 100644 --- a/sbin/ipf/ipscan/ipscan.5 +++ b/sbin/ipf/ipscan/ipscan.5 @@ -1,51 +1,50 @@ .\" .TH IPSCAN 5 .SH NAME ipscan, ipscan.conf \- ipscan file format .SH DESCRIPTION -.PP WARNING: This feature is to be considered experimental and may change significantly until a final implementation is drawn up. .PP The format for files accept by ipscan currently follow this rough grammar: .LP .nf line ::= name ":" matchup [ "," matchup ] "=" action . matchup ::= "(" ")" | "(" literal ")" | "(" literal "," match ")" . action ::= result | result "else" result . result ::= "close" | "track" | redirect . redirect ::= "redirect" ip-address [ "(" "," port-number ")" ] . match ::= { match-char } match-char ::= "*" | "?" | "." .fi .PP In this example an ip-address is a dotted-quad IPv4 address and a port-number is a number between 1 and 65535, inclusive. The match string is must be of same length as the literal string that it is matching (literal). The length of either string is limited to 16 bytes. .PP Currently, the redirect option is not yet been implemented. .LP .nf # # * = match any character, . = exact match, ? = case insensitive # # Scan for anything that looks like HTTP and redirect it to the local # proxy. One catch - this feature (redirect) is not yet implemented. # http : ("GET ", "???." ) = redirect(127.0.0.1) # # Track ssh connections (i.e do nothing) # ssh : (), ("SSH-") = track # # Things which look like smtp to be tracked else closed. # Client can start with EHLO (ESMTP) or HELO (SMTP). # smtp : ("HELO ", "**??."), ("220 ", "....") = track else close # .fi .SH FILES /etc/ipscan.conf .SH SEE ALSO ipscan(8) diff --git a/sbin/ipf/ipscan/ipscan.8 b/sbin/ipf/ipscan/ipscan.8 index 292d5764519a..da4068a1e8f2 100644 --- a/sbin/ipf/ipscan/ipscan.8 +++ b/sbin/ipf/ipscan/ipscan.8 @@ -1,43 +1,42 @@ .\" .TH IPSCAN 8 .SH NAME ipscan \- user interface to the IPFilter content scanning .SH SYNOPSIS .B ipscan [ .B \-dlnrsv ] [ ] .B \-f <\fIfilename\fP> .SH DESCRIPTION -.PP \fBipscan\fP opens the filename given (treating "\-" as stdin) and parses the file to build up a content scanning configuration to load into the kernel. Currently only the first 16 bytes of a connection can be compared. .SH OPTIONS .TP .B \-d Toggle debugging of processing the configuration file. .TP .B \-l Show the list of currently configured content scanning entries. .TP .B \-n This flag (no-change) prevents \fBipscan\fP from actually making any ioctl calls or doing anything which would alter the currently running kernel. .TP .B \-r Remove commands from kernel configuration as they are read from the configuration file rather than adding new ones. .TP .B \-s Retrieve and display content scanning statistics .TP .B \-v Turn verbose mode on. .DT .SH FILES /dev/ipscan /etc/ipscan.conf .SH SEE ALSO ipscan(5), ipf(8) diff --git a/sbin/ipf/ipsend/ipresend.1 b/sbin/ipf/ipsend/ipresend.1 index 529c1649b756..e7714349e6af 100644 --- a/sbin/ipf/ipsend/ipresend.1 +++ b/sbin/ipf/ipsend/ipresend.1 @@ -1,107 +1,104 @@ .\" .TH IPRESEND 1 .SH NAME ipresend \- resend IP packets out to network .SH SYNOPSIS .B ipresend [ .B \-EHPRSTX ] [ .B \-d ] [ .B \-g <\fIgateway\fP> ] [ .B \-m <\fIMTU\fP> ] [ .B \-r <\fIfilename\fP> ] .SH DESCRIPTION -.PP \fBipresend\fP was designed to allow packets to be resent, once captured, back out onto the network for use in testing. \fIipresend\fP supports a number of different file formats as input, including saved snoop/tcpdump binary data. .SH OPTIONS .TP .BR \-d \0 Set the interface name to be the name supplied. This is useful with the \fB\-P, \-S, \-T\fP and \fB\-E\fP options, where it is not otherwise possible to associate a packet with an interface. Normal "text packets" can override this setting. .TP .BR \-g \0 Specify the hostname of the gateway through which to route packets. This is required whenever the destination host isn't directly attached to the same network as the host from which you're sending. .TP .BR \-m \0 Specify the MTU to be used when sending out packets. This option allows you to set a fake MTU, allowing the simulation of network interfaces with small MTU's without setting them so. .TP .BR \-r \0 Specify the filename from which to take input. Default is stdin. .TP .B \-E The input file is to be text output from etherfind. The text formats which are currently supported are those which result from the following etherfind option combinations: .PP .nf etherfind -n etherfind -n -t .fi .LP .TP .B \-H The input file is to be hex digits, representing the binary makeup of the packet. No length correction is made, if an incorrect length is put in the IP header. .TP .B \-P The input file specified by \fB\-i\fP is a binary file produced using libpcap (i.e., tcpdump version 3). Packets are read from this file as being input (for rule purposes). .TP .B \-R When sending packets out, send them out "raw" (the way they came in). The only real significance here is that it will expect the link layer (i.e. ethernet) headers to be prepended to the IP packet being output. .TP .B \-S The input file is to be in "snoop" format (see RFC 1761). Packets are read from this file and used as input from any interface. This is perhaps the most useful input type, currently. .TP .B \-T The input file is to be text output from tcpdump. The text formats which are currently supported are those which result from the following tcpdump option combinations: .PP .nf tcpdump -n tcpdump -nq tcpdump -nqt tcpdump -nqtt tcpdump -nqte .fi .LP .TP .B \-X The input file is composed of text descriptions of IP packets. .DT .SH SEE ALSO snoop(1m), tcpdump(8), etherfind(8c), ipftest(1), ipresend(1), iptest(1), bpf(4), dlpi(7p) .SH DIAGNOSTICS -.PP Needs to be run as root. .SH BUGS -.PP Not all of the input formats are sufficiently capable of introducing a wide enough variety of packets for them to be all useful in testing. If you find any, please send email to me at darrenr@pobox.com diff --git a/sbin/ipf/ipsend/ipsend.1 b/sbin/ipf/ipsend/ipsend.1 index d0770c41775e..57d29ba8569a 100644 --- a/sbin/ipf/ipsend/ipsend.1 +++ b/sbin/ipf/ipsend/ipsend.1 @@ -1,110 +1,107 @@ .\" .TH IPSEND 1 .SH NAME ipsend \- sends IP packets .SH SYNOPSIS .B ipsend [ .B \-dITUv ] [ .B \-i ] [ .B \-f <\fIoffset\fP> ] [ .B \-g <\fIgateway\fP> ] [ .B \-m <\fIMTU\fP> ] [ .B \-o <\fIoption\fP> ] [ .B \-P ] [ .B \-s <\fIsource\fP> ] [ .B \-t <\fIdest. port\fP> ] [ .B \-w <\fIwindow\fP> ] [TCP-flags] .SH DESCRIPTION -.PP \fBipsend\fP can be compiled in two ways. The first is used to send one-off packets to a destination host, using command line options to specify various attributes present in the headers. The \fIdestination\fP must be given as the last command line option, except for when TCP flags are specified as a combination of A, S, F, U, P and R, last. .PP The other way it may be compiled, with DOSOCKET defined, is to allow an attempt at making a TCP connection using a with ipsend resending the SYN packet as per the command line options. .SH OPTIONS .TP .BR \-d enable debugging mode. .TP .BR \-f \0 The \fI-f\fP allows the IP offset field in the IP header to be set to an arbitrary value, which can be specified in decimal or hexadecimal. .TP .BR \-g \0 Specify the hostname of the gateway through which to route packets. This is required whenever the destination host isn't directly attached to the same network as the host from which you're sending. .TP .BR \-i \0 Set the interface name to be the name supplied. .TP .TP .BR \-m \0 Specify the MTU to be used when sending out packets. This option allows you to set a fake MTU, allowing the simulation of network interfaces with small MTU's without setting them so. .TP .BR \-o \0