bsd/man/man4/ipfirewall.4

   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 .\"--------------------------------------------------------------------------------------------
  17 IPFirewall (sometimes referred to as "ipfw") is a system facility which allows filtering,
  18 redirecting, and other operations on IP packets travelling through network interfaces.  Packets
  19 are matched by applying an ordered list of pattern rules against each packet until a match is
  20 found, at which point the corresponding action is taken.  Rules are numbered from 1 to 65534;
  21 multiple rules may share the same number.
  22 .Pp
  23 There is one rule that always exists, rule number 65535.  This rule normally causes all packets
  24 to be dropped.  Hence, any packet which does not match a lower numbered rule will be dropped.
  25 However, the kernel compile time option
  26 .Dv IPFIREWALL_DEFAULT_TO_ACCEPT
  27 allows the administrator to change this fixed rule to permit everything.
  28 .Pp
  29 The buffer passed down via the socket-option call should contain a "struct ip_fw" that is
  30 initialized with the required parameters for the firewall command being invoked.  This
  31 structure is consistently required for every firewall command, even though in some cases
  32 the majority of its fields will go unused.  The reason for this is the API versioning that
  33 the firewall supports for the sake of backward compatibility.  The
  34 .Dv version
  35 field of this
  36 structure should always be set to
  37 .Dv IP_FW_CURRENT_API_VERSION
  38 or an EINVAL error will be returned.
  39 .Ss Commands
  40 The following socket options are used to manage the rule list:
  41 .Bl -tag -width "IP_FW_FLUSH"
  42 .It Dv IP_FW_ADD
  43 inserts the rule into the rule list
  44 .It Dv IP_FW_DEL
  45 deletes all rules having the matching rule number
  46 .It Dv IP_FW_GET
  47 returns the (first) rule having the matching rule number
  48 .It Dv IP_FW_ZERO
  49 zeros the statistics associated with all rules having the
  50 matching rule number.
  51 If the rule number is zero, all rules are zeroed.
  52 .It Dv IP_FW_FLUSH
  53 removes all rules (except 65535).
  54 .El
  55 .Pp
  56 When the kernel security level is greater than 2, only
  57 .Dv IP_FW_GET
  58 is allowed.
  59 .\"--------------------------------------------------------------------------------------------
  60 .Ss Rule Structure
  61 .\"--------------------------------------------------------------------------------------------
  62 Rules are described by the following structure:
  63 .Bd -literal
  64 /* One ipfw rule */
  65 struct 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
 109 The ip_fw.h header also contains macros for setting the fw_ports field and various
 110 flags and constants for setting other fields.
 111 .Ed
 112 .\"--------------------------------------------------------------------------------------------
 113 .Ss Rule Actions
 114 .\"--------------------------------------------------------------------------------------------
 115 Each 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
 118 drop packet
 119 .It Dv IP_FW_F_REJECT
 120 drop packet; send rejection via ICMP or TCP
 121 .It Dv IP_FW_F_ACCEPT
 122 accept packet
 123 .It Dv IP_FW_F_COUNT
 124 increment counters; continue matching
 125 .It Dv IP_FW_F_DIVERT
 126 divert packet to a
 127 .Xr divert 4
 128 socket
 129 .It Dv IP_FW_F_TEE
 130 copy packet to a
 131 .Xr divert 4
 132 socket; continue
 133 .It Dv IP_FW_F_SKIPTO
 134 skip to rule number
 135 .Va fu_skipto_rule
 136 .El
 137 .Pp
 138 In the case of
 139 .Dv IP_FW_F_REJECT ,
 140 if the
 141 .Va fu_reject_code
 142 is a number from 0 to 255, then an ICMP unreachable packet is sent back to the
 143 original packet's source IP address, with the corresponding code.  Otherwise, the
 144 value must be 256 and the protocol
 145 .Dv IPPROTO_TCP ,
 146 in which case a TCP reset packet is sent instead.
 147 .Pp
 148 With
 149 .Dv IP_FW_F_SKIPTO ,
 150 all succeeding rules having rule number less than
 151 .Va fu_skipto_rule
 152 are skipped.
 153 .Ss Kernel Options
 154 Options in the kernel configuration file:
 155 .Bl -tag -width "options IPFIREWALL_VERBOSE_LIMIT"
 156 .It Cd options IPFIREWALL
 157 enable
 158 .Nm
 159 .It Cd options IPFIREWALL_VERBOSE
 160 enable firewall logging
 161 .It Cd options IPFIREWALL_VERBOSE_LIMIT
 162 limit firewall logging
 163 .It Cd options IPDIVERT
 164 enable
 165 .Xr divert 4
 166 sockets
 167 .El
 168 .Pp
 169 When packets match a rule with the
 170 .Dv IP_FW_F_PRN
 171 bit set, and if
 172 .Dv IPFIREWALL_VERBOSE
 173 has been enabled,a message is written to
 174 .Pa /dev/klog
 175 with the
 176 .Dv LOG_SECURITY
 177 facility
 178 (see
 179 .Xr syslog 3 )
 180 for further logging by
 181 .Xr syslogd 8 ;
 182 .Dv IPFIREWALL_VERBOSE_LIMIT
 183 limits the maximum number of times each rule can cause a log message. These variables are also
 184 available via the
 185 .Xr sysctl 3
 186 interface.
 187 .\"--------------------------------------------------------------------------------------------
 188 .Sh RETURN VALUES
 189 .\"--------------------------------------------------------------------------------------------
 190 The
 191 .Fn setsockopt
 192 function returns 0 on success.  Otherwise, -1 is returned and the global variable
 193 .Va errno
 194 is set to indicate the error.
 195 .\"--------------------------------------------------------------------------------------------
 196 .Sh ERRORS
 197 .\"--------------------------------------------------------------------------------------------
 198 The
 199 .Fn setsockopt
 200 function will fail if:
 201 .Bl -tag -width Er
 202 .It Bq Er EINVAL
 203 The IP option field was improperly formed;
 204 an option field was shorter than the minimum value
 205 or longer than the option buffer provided.
 206 .It Bq Er EINVAL
 207 A 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
 210 The version field of the ip_fw structure was set to a value not supported by the
 211 currently-installed
 212 .Dv IPFirewall,
 213 or no ip_fw structure was passed to it at all.
 214 .It Bq Er EINVAL
 215 An 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 .\"--------------------------------------------------------------------------------------------
 229 The ``tee'' rule is not yet implemented (currently it has no effect).
 230 .Pp
 231 This man page still needs work.
 232 .\"--------------------------------------------------------------------------------------------
 233 .Sh HISTORY
 234 .\"--------------------------------------------------------------------------------------------
 235 The ipfw facility was initially written as package to BSDI by
 236 .An Daniel Boulet
 237 .Aq danny@BouletFermat.ab.ca .
 238 It has been heavily modified and ported to
 239 .Fx
 240 by
 241 .An Ugen J.S. Antsilevich
 242 .Aq ugen@NetVision.net.il .
 243 .Pp
 244 Several enhancements added by
 245 .An Archie Cobbs
 246 .Aq archie@FreeBSD.org .