1.\" 2.\" $Id: ipfirewall.4,v 1.12 1997/09/29 10:10:15 wosch Exp $ 3.\" 4.Dd June 22, 1997 5.Dt IPFIREWALL 4 6.Os 7.Sh NAME 8.Nm ipfirewall 9.Nd IP packet filter and traffic accounting 10.Sh SYNOPSIS 11.Fd #include <sys/types.h> 12.Fd #include <sys/queue.h> 13.Fd #include <netinet/in.h> 14.Fd #include <netinet/ip_fw.h> 15.Ft int 16.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size 17.Sh DESCRIPTION 18Ipfirewall (alias ipfw) is a system facility which allows filtering, 19redirecting, and other operations on IP packets travelling through 20system interfaces. Packets are matched by applying an ordered list 21of pattern rules against each packet until a match is found, at 22which point the corresponding action is taken. Rules are numbered 23from 1 to 65534; multiple rules may share the same number. 24.Pp 25There is one rule that always exists, rule number 65535. This rule 26normally causes all packets to be dropped. Hence, any packet which does not 27match a lower numbered rule will be dropped. However, a kernel compile 28time option 29.Dq IPFIREWALL_DEFAULT_TO_ACCEPT 30allows the administrator to change this fixed rule to permit everything. 31.Pp 32The value passed to 33.Fn setsockopt 34is a struct ip_fw describing the rule (see below). In some cases 35(such as IP_FW_DEL), only the rule number is significant. 36.Sh COMMANDS 37The following socket options are used to manage the rule list: 38.Pp 39IP_FW_ADD inserts the rule into the rule list. 40.Pp 41IP_FW_DEL deletes all rules having the matching rule number. 42.Pp 43IP_FW_GET returns the (first) rule having the matching rule number. 44.Pp 45IP_FW_ZERO zeros the statistics associated with all rules having the 46matching rule number. If the rule number is zero, all rules are zeroed. 47.Pp 48IP_FW_FLUSH removes all rules (except 65535). 49.Pp 50When the kernel security level is greater than 2, only IP_FW_GET 51is allowed. 52.Sh RULE STRUCTURE 53Rules are described by the following structure: 54.Bd -literal 55/* Specify an interface */ 56union ip_fw_if { 57 struct in_addr fu_via_ip; /* Specified by IP address */ 58 struct { /* Specified by interface name */ 59#define FW_IFNLEN 6 /* To keep structure on 2^x boundary */ 60 char name[FW_IFNLEN]; 61 short unit; /* -1 means match any unit */ 62 } fu_via_if; 63}; 64 65/* One ipfw rule */ 66struct ip_fw { 67 u_long fw_pcnt,fw_bcnt; /* Packet and byte counters */ 68 struct in_addr fw_src, fw_dst; /* Source and destination IP addr */ 69 struct in_addr fw_smsk, fw_dmsk;/* Mask for src and dest IP addr */ 70 u_short fw_number; /* Rule number */ 71 u_short fw_flg; /* Flags word */ 72#define IP_FW_MAX_PORTS 10 /* A reasonable maximum */ 73 u_short fw_pts[IP_FW_MAX_PORTS];/* Array of port numbers to match */ 74 u_char fw_ipopt,fw_ipnopt; /* IP options set/unset */ 75 u_char fw_tcpf,fw_tcpnf; /* TCP flags set/unset */ 76#define IP_FW_ICMPTYPES_DIM (256 / (sizeof(unsigned) * 8)) 77 unsigned fw_icmptypes[IP_FW_ICMPTYPES_DIM]; /* ICMP types bitmap */ 78 long timestamp; /* timestamp (tv_sec) of last match */ 79 union ip_fw_if fw_in_if, fw_out_if;/* Incoming / outgoing interfaces */ 80 union { 81 u_short fu_divert_port; /* Divert/tee port */ 82 u_short fu_skipto_rule; /* SKIPTO command rule number */ 83 u_short fu_reject_code; /* REJECT response code */ 84 } fw_un; 85 u_char fw_prot; /* IP protocol */ 86 u_char fw_nports; /* N'of src ports and # of dst ports */ 87 /* in ports array (dst ports follow */ 88 /* src ports; max of 10 ports in all */ 89 /* count of 0 means match all ports) */ 90}; 91 92/* Encoding of number of source/dest ports from "fw_nports" */ 93 94#define IP_FW_GETNSRCP(rule) ((rule)->fw_nports & 0x0f) 95#define IP_FW_SETNSRCP(rule, n) do { \\ 96 (rule)->fw_nports &= ~0x0f; \\ 97 (rule)->fw_nports |= (n); \\ 98 } while (0) 99#define IP_FW_GETNDSTP(rule) ((rule)->fw_nports >> 4) 100#define IP_FW_SETNDSTP(rule, n) do { \\ 101 (rule)->fw_nports &= ~0xf0; \\ 102 (rule)->fw_nports |= (n) << 4;\\ 103 } while (0) 104 105/* Flags values for "flags" field */ 106 107#define IP_FW_F_IN 0x0001 /* Check inbound packets */ 108#define IP_FW_F_OUT 0x0002 /* Check outbound packets */ 109#define IP_FW_F_IIFACE 0x0004 /* Apply inbound interface test */ 110#define IP_FW_F_OIFACE 0x0008 /* Apply outbound interface test */ 111 112#define IP_FW_F_COMMAND 0x0070 /* Mask for type of chain entry: */ 113#define IP_FW_F_DENY 0x0000 /* This is a deny rule */ 114#define IP_FW_F_REJECT 0x0010 /* Deny and send a response packet */ 115#define IP_FW_F_ACCEPT 0x0020 /* This is an accept rule */ 116#define IP_FW_F_COUNT 0x0030 /* This is a count rule */ 117#define IP_FW_F_DIVERT 0x0040 /* This is a divert rule */ 118#define IP_FW_F_TEE 0x0050 /* This is a tee rule */ 119#define IP_FW_F_SKIPTO 0x0060 /* This is a skipto rule */ 120 121#define IP_FW_F_PRN 0x0080 /* Print if this rule matches */ 122 123#define IP_FW_F_SRNG 0x0100 /* The first two src ports are a min * 124 * and max range (stored in host byte * 125 * order). */ 126 127#define IP_FW_F_DRNG 0x0200 /* The first two dst ports are a min * 128 * and max range (stored in host byte * 129 * order). */ 130 131#define IP_FW_F_IIFNAME 0x0400 /* In interface by name/unit (not IP) */ 132#define IP_FW_F_OIFNAME 0x0800 /* Out interface by name/unit (not IP) */ 133 134#define IP_FW_F_INVSRC 0x1000 /* Invert sense of src check */ 135#define IP_FW_F_INVDST 0x2000 /* Invert sense of dst check */ 136 137#define IP_FW_F_FRAG 0x4000 /* Fragment */ 138 139#define IP_FW_F_ICMPBIT 0x8000 /* ICMP type bitmap is valid */ 140 141#define IP_FW_F_MASK 0xFFFF /* All possible flag bits mask */ 142.Ed 143 144.Sh RULE ACTIONS 145Each rule has an action described by the IP_FW_F_COMMAND bits in the 146flags word: 147 148 IP_FW_F_DENY - drop packet 149 IP_FW_F_REJECT - drop packet; send rejection via ICMP or TCP 150 IP_FW_F_ACCEPT - accept packet 151 IP_FW_F_COUNT - increment counters; continue matching 152 IP_FW_F_DIVERT - divert packet to a divert(4) socket 153 IP_FW_F_TEE - copy packet to a divert(4) socket; continue 154 IP_FW_F_SKIPTO - skip to rule number fu_skipto_rule 155.Pp 156In the case of IP_FW_F_REJECT, if the fu_reject_code is a number 157from 0 to 255, then an ICMP unreachable packet is sent back to the 158original packet's source IP address, with the corresponding code. 159Otherwise, the value must be 256 and the protocol IPPROTO_TCP, 160in which case a TCP reset packet is sent instead. 161.Pp 162With IP_FW_F_SKIPTO, all succeeding rules having rule number less 163than fu_skipto_rule are skipped. 164.Sh KERNEL OPTIONS 165Options in the kernel configuration file: 166 IPFIREWALL - enable ipfirewall. 167 IPFIREWALL_VERBOSE - enable firewall output 168 IPFIREWALL_VERBOSE_LIMIT - limit firewall output 169 DIVERT - enable divert(4) sockets. 170.Pp 171When packets match a rule with the IP_FW_F_PRN bit set, a message 172is logged to the console if IPFIREWALL_VERBOSE has been enabled; 173IPFIREWALL_VERBOSE_LIMIT limits the maximum number of times each 174rule can cause a log message. These variables are also 175available via the 176.Xr sysctl 3 177interface. 178.Sh DIAGNOSTICS 179 180[EINVAL] The IP option field was improperly formed; an option 181 field was shorter than the minimum value or longer than 182 the option buffer provided. A structural error in 183 ip_fw structure occurred (n_src_p+n_dst_p too big, 184 ports set for ALL/ICMP protocols etc.). An invalid 185 rule number was used. 186.Sh SEE ALSO 187.Xr setsockopt 2 , 188.Xr divert 4 , 189.Xr ip 4 , 190.Xr ipfw 8 , 191.Xr sysctl 8 . 192.Sh BUGS 193The ``tee'' rule is not yet implemented (currently it has no effect). 194.Pp 195This man page still needs work. 196.Sh HISTORY 197The ipfw facility was initially written as package to BSDI 198by Daniel Boulet <danny@BouletFermat.ab.ca>. 199It has been heavily modified and ported to FreeBSD 200by Ugen J.S.Antsilevich <ugen@NetVision.net.il>. 201.Pp 202Several enhancements added by Archie Cobbs <archie@whistle.com>. 203