1.Dd June 22, 1997 2.Dt IPFIREWALL 4 3.Os Darwin 4.Sh NAME 5.Nm ipfirewall 6.Nd IP packet filter and traffic accounting 7.Sh SYNOPSIS 8.Fd #include <sys/types.h> 9.Fd #include <sys/queue.h> 10.Fd #include <netinet/in.h> 11.Fd #include <netinet/ip_fw.h> 12.Ft int 13.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size 14.\"-------------------------------------------------------------------------------------------- 15.Sh DESCRIPTION 16.\"-------------------------------------------------------------------------------------------- 17IPFirewall (sometimes referred to as "ipfw") is a system facility which allows filtering, 18redirecting, and other operations on IP packets travelling through network interfaces. Packets 19are matched by applying an ordered list of pattern rules against each packet until a match is 20found, at which point the corresponding action is taken. Rules are numbered from 1 to 65534; 21multiple rules may share the same number. 22.Pp 23There is one rule that always exists, rule number 65535. This rule normally causes all packets 24to be dropped. Hence, any packet which does not match a lower numbered rule will be dropped. 25However, the kernel compile time option 26.Dv IPFIREWALL_DEFAULT_TO_ACCEPT 27allows the administrator to change this fixed rule to permit everything. 28.Pp 29The buffer passed down via the socket-option call should contain a "struct ip_fw" that is 30initialized with the required parameters for the firewall command being invoked. This 31structure is consistently required for every firewall command, even though in some cases 32the majority of its fields will go unused. The reason for this is the API versioning that 33the firewall supports for the sake of backward compatibility. The 34.Dv version 35field of this 36structure should always be set to 37.Dv IP_FW_CURRENT_API_VERSION 38or an EINVAL error will be returned. 39.Ss Commands 40The following socket options are used to manage the rule list: 41.Bl -tag -width "IP_FW_FLUSH" 42.It Dv IP_FW_ADD 43inserts the rule into the rule list 44.It Dv IP_FW_DEL 45deletes all rules having the matching rule number 46.It Dv IP_FW_GET 47returns the (first) rule having the matching rule number 48.It Dv IP_FW_ZERO 49zeros the statistics associated with all rules having the 50matching rule number. 51If the rule number is zero, all rules are zeroed. 52.It Dv IP_FW_FLUSH 53removes all rules (except 65535). 54.El 55.Pp 56When the kernel security level is greater than 2, only 57.Dv IP_FW_GET 58is allowed. 59.\"-------------------------------------------------------------------------------------------- 60.Ss Rule Structure 61.\"-------------------------------------------------------------------------------------------- 62Rules are described by the following structure: 63.Bd -literal 64/* One ipfw rule */ 65struct ip_fw { 66 u_int32_t version; /* Version of this structure. Should always be */ 67 /* set to IP_FW_CURRENT_API_VERSION by clients. */ 68 void *context; /* Context that is usable by user processes to */ 69 /* identify this rule. */ 70 u_int64_t fw_pcnt,fw_bcnt; /* Packet and byte counters */ 71 struct in_addr fw_src, fw_dst; /* Source and destination IP addr */ 72 struct in_addr fw_smsk, fw_dmsk; /* Mask for src and dest IP addr */ 73 u_short fw_number; /* Rule number */ 74 u_int fw_flg; /* Flags word */ 75#define IP_FW_MAX_PORTS 10 /* A reasonable maximum */ 76 union { 77 u_short fw_pts[IP_FW_MAX_PORTS]; /* Array of port numbers to match */ 78#define IP_FW_ICMPTYPES_MAX 128 79#define IP_FW_ICMPTYPES_DIM (IP_FW_ICMPTYPES_MAX / (sizeof(unsigned) * 8)) 80 unsigned fw_icmptypes[IP_FW_ICMPTYPES_DIM]; /* ICMP types bitmap */ 81 } fw_uar; 82 u_int fw_ipflg; /* IP flags word */ 83 u_char fw_ipopt,fw_ipnopt; /* IP options set/unset */ 84 u_char fw_tcpopt,fw_tcpnopt; /* TCP options set/unset */ 85 u_char fw_tcpf,fw_tcpnf; /* TCP flags set/unset */ 86 long timestamp; /* timestamp (tv_sec) of last match */ 87 union ip_fw_if fw_in_if, fw_out_if; /* Incoming and outgoing interfaces */ 88 union { 89 u_short fu_divert_port; /* Divert/tee port (options IPDIVERT) */ 90 u_short fu_pipe_nr; /* queue number (option DUMMYNET) */ 91 u_short fu_skipto_rule; /* SKIPTO command rule number */ 92 u_short fu_reject_code; /* REJECT response code */ 93 struct sockaddr_in fu_fwd_ip; 94 } fw_un; 95 u_char fw_prot; /* IP protocol */ 96 /* 97 * N'of src ports and # of dst ports in ports array (dst ports 98 * follow src ports; max of 10 ports in all; count of 0 means 99 * match all ports) 100 */ 101 u_char fw_nports; 102 void *pipe_ptr; /* flow_set ptr for dummynet pipe */ 103 void *next_rule_ptr ; /* next rule in case of match */ 104 uid_t fw_uid; /* uid to match */ 105 int fw_logamount; /* amount to log */ 106 u_int64_t fw_loghighest; /* highest number packet to log */ 107}; 108 109The ip_fw.h header also contains macros for setting the fw_ports field and various 110flags and constants for setting other fields. 111.Ed 112.\"-------------------------------------------------------------------------------------------- 113.Ss Rule Actions 114.\"-------------------------------------------------------------------------------------------- 115Each rule has an action described by the IP_FW_F_COMMAND bits in the flags word: 116.Bl -tag -width "IP_FW_F_DIVERT" 117.It Dv IP_FW_F_DENY 118drop packet 119.It Dv IP_FW_F_REJECT 120drop packet; send rejection via ICMP or TCP 121.It Dv IP_FW_F_ACCEPT 122accept packet 123.It Dv IP_FW_F_COUNT 124increment counters; continue matching 125.It Dv IP_FW_F_DIVERT 126divert packet to a 127.Xr divert 4 128socket 129.It Dv IP_FW_F_TEE 130copy packet to a 131.Xr divert 4 132socket; continue 133.It Dv IP_FW_F_SKIPTO 134skip to rule number 135.Va fu_skipto_rule 136.El 137.Pp 138In the case of 139.Dv IP_FW_F_REJECT , 140if the 141.Va fu_reject_code 142is a number from 0 to 255, then an ICMP unreachable packet is sent back to the 143original packet's source IP address, with the corresponding code. Otherwise, the 144value must be 256 and the protocol 145.Dv IPPROTO_TCP , 146in which case a TCP reset packet is sent instead. 147.Pp 148With 149.Dv IP_FW_F_SKIPTO , 150all succeeding rules having rule number less than 151.Va fu_skipto_rule 152are skipped. 153.Ss Kernel Options 154Options in the kernel configuration file: 155.Bl -tag -width "options IPFIREWALL_VERBOSE_LIMIT" 156.It Cd options IPFIREWALL 157enable 158.Nm 159.It Cd options IPFIREWALL_VERBOSE 160enable firewall logging 161.It Cd options IPFIREWALL_VERBOSE_LIMIT 162limit firewall logging 163.It Cd options IPDIVERT 164enable 165.Xr divert 4 166sockets 167.El 168.Pp 169When packets match a rule with the 170.Dv IP_FW_F_PRN 171bit set, and if 172.Dv IPFIREWALL_VERBOSE 173has been enabled,a message is written to 174.Pa /dev/klog 175with the 176.Dv LOG_SECURITY 177facility 178(see 179.Xr syslog 3 ) 180for further logging by 181.Xr syslogd 8 ; 182.Dv IPFIREWALL_VERBOSE_LIMIT 183limits the maximum number of times each rule can cause a log message. These variables are also 184available via the 185.Xr sysctl 3 186interface. 187.\"-------------------------------------------------------------------------------------------- 188.Sh RETURN VALUES 189.\"-------------------------------------------------------------------------------------------- 190The 191.Fn setsockopt 192function returns 0 on success. Otherwise, -1 is returned and the global variable 193.Va errno 194is set to indicate the error. 195.\"-------------------------------------------------------------------------------------------- 196.Sh ERRORS 197.\"-------------------------------------------------------------------------------------------- 198The 199.Fn setsockopt 200function will fail if: 201.Bl -tag -width Er 202.It Bq Er EINVAL 203The IP option field was improperly formed; 204an option field was shorter than the minimum value 205or longer than the option buffer provided. 206.It Bq Er EINVAL 207A structural error in ip_fw structure occurred 208(n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.). 209.It Bq Er EINVAL 210The version field of the ip_fw structure was set to a value not supported by the 211currently-installed 212.Dv IPFirewall, 213or no ip_fw structure was passed to it at all. 214.It Bq Er EINVAL 215An invalid rule number was used. 216.El 217.\"-------------------------------------------------------------------------------------------- 218.Sh SEE ALSO 219.\"-------------------------------------------------------------------------------------------- 220.Xr setsockopt 2 , 221.Xr divert 4 , 222.Xr ip 4 , 223.Xr ipfw 8 , 224.Xr sysctl 8 , 225.Xr syslogd 8 226.\"-------------------------------------------------------------------------------------------- 227.Sh BUGS 228.\"-------------------------------------------------------------------------------------------- 229The ``tee'' rule is not yet implemented (currently it has no effect). 230.Pp 231This man page still needs work. 232.\"-------------------------------------------------------------------------------------------- 233.Sh HISTORY 234.\"-------------------------------------------------------------------------------------------- 235The ipfw facility was initially written as package to BSDI by 236.An Daniel Boulet 237.Aq danny@BouletFermat.ab.ca . 238It has been heavily modified and ported to 239.Fx 240by 241.An Ugen J.S. Antsilevich 242.Aq ugen@NetVision.net.il . 243.Pp 244Several enhancements added by 245.An Archie Cobbs 246.Aq archie@FreeBSD.org . 247