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