Penguin
Recent Changes
Annotated edit history of ipfw(4) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 IPFW
2 !!!IPFW
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 COMMANDS
7 STRUCTURES
8 CHANGES
9 RETURN VALUE
10 LISTING RULES
11 FILES
12 BUGS
13 SEE ALSO
14 ----
15 !!NAME
16
17
18 ipfw - IP firewall
19 !!SYNOPSIS
20
21
22 __#include __
23 #include __
24 #include __
25 #include __
26 #include __
27 #include __
28 #include __
29 #include __
30 #include __
31
32
33 __int setsockopt (int__ ''socket''__, IPPROTO_IP,
34 int__ ''command''__, void *__''data''__, int__
35 ''length''__)__
36 !!DESCRIPTION
37
38
39 The IP firewall facilities in the Linux kernel provide
40 mechanisms for accounting IP packets, for building firewalls
41 based on packet-level filtering, for building firewalls
42 using transparent proxy servers (by redirecting packets to
43 local sockets), and for masquerading forwarded packets. The
44 administration of these functions is maintained in the
45 kernel as a series of separate lists (hereafter referred to
46 as chains) each containing zero or more rules. There are
47 three builtin chains which are called input, forward and
48 output which always exist. All other chains are user
49 defined. A chain is a sequence of rules; each rule contains
50 specific information about source and destination addresses,
51 protocols, port numbers, and some other characteristics.
52 Information about what to do if a packet matches the rule is
53 also contained. A packet will match with a rule when the
54 characteristics of the rule match those of the IP
55 packet.
56
57
58 A packet always traverses a chain starting at rule number 1.
59 Each rule specifies what to do when a packet matches. If a
60 packet does not match a rule, the next rule in that chain is
61 tried. If the end of a builtin chain is reached the default
62 policy for that chain is returned. If the end of a user
63 defined chain is reached then the rule after the rule which
64 branched to that chain is tried. The purpose of the three
65 builtin chains are
66
67
68 Input firewall
69
70
71 These rules regulate the acceptance of incoming IP packets.
72 All packets coming in via one of the local network
73 interfaces are checked against the input firewall rules
74 (locally-generated packets are considered to come from the
75 loopback interface). A rule which matches a packet will
76 cause the rule's packet and byte counters to be incremented
77 appropriately.
78
79
80 Forwarding firewall
81
82
83 These rules define the permissions for forwarding IP
84 packets. All packets sent by a remote host having another
85 remote host as destination are checked against the
86 forwarding firewall rules. A rule which matches will cause
87 the rule's packet and byte counters to be incremented
88 appropriately.
89
90
91 Output firewall
92
93
94 These rules define the permissions for sending IP packets.
95 All packets that are ready to be be sent via one of the
96 local network interfaces are checked against the output
97 firewall rules. A rule which matches will cause the rule's
98 packet and byte counters to be incremented
99 appropriately.
100
101
102 Each of the firewall rules contains either a branch name or
103 a policy, which specifies what action has to be taken when a
104 packet matches with the rule. There are five different
105 policies possible: ''ACCEPT'' (let the packet pass the
106 firewall), ''REJECT'' (do not accept the packet and send
107 an ICMP host unreachable message back to the sender as
108 notification), ''DENY'' (sometimes referred to as block;
109 ignore the packet without sending any notification),
110 ''REDIRECT'' (redirected to a local socket - input rules
111 only) and ''MASQ'' (pass the packet, but perform IP
112 masquerading - forwarding rules only).
113
114
115 The last two are special; for ''REDIRECT'', the packet
116 will be received by a local process, even if it was sent to
117 another host and/or another port number. This function only
118 applies to TCP or UDP packets.
119
120
121 For ''MASQ'', the sender address in the IP packets is
122 replaced by the address of the local host and the source
123 port in the TCP or UDP header is replaced by a locally
124 generated (temporary) port number before being forwarded.
125 Because this administration is kept in the kernel, reverse
126 packets (sent to the temporary port number on the local
127 host) are recognized automatically. The destination address
128 and port number of these packets will be replaced by the
129 original address and port number that was saved when the
130 first packet was masqueraded. This function only applies to
131 TCP or UDP packets.
132
133
134 There is also a special target ''RETURN'' which is
135 equivalent to falling off the end of the chain.
136
137
138 This paragraph describes the way a packet goes through the
139 firewall. Packets received via one of the local network
140 interfaces will pass the following chains:
141
142
143 ''input firewall'' (incoming device) Here, the device
144 (network interface) that is used when trying to match a rule
145 with an IP packet is listed between brackets. After this
146 step, a packet will optionally be redirected to a local
147 socket. When a packet has to be forwarded to a remote host,
148 it will also pass the next set of rules: ''forwarding
149 firewall'' (outgoing device) After this step, a packet
150 will optionally be masqueraded. Responses to masqueraded
151 packets will never pass the forwarding firewall (but they
152 will pass both the input and output firewalls). All packets
153 sent via one of the local network interfaces, either locally
154 generated or being forwarded, will pass the following sets
155 of rules: ''output firewall'' (outgoing
156 device)
157
158
159 When a packet enters one of the three above chains rules are
160 traversed from the first rule in order. When analysing a
161 rule one of three things may occur.
162
163
164 Rule unmatched:
165
166
167 If a rule is unmatched then the next rule in that chain is
168 analysed. If there are no more rules for that chain the
169 default policy for that chain is returned (or traversal
170 continues back at the calling chain, in the case of a
171 user-defined chain).
172
173
174 Rule matched (with branch to chain):
175
176
177 When a rule is matched by a packet and the rule contains a
178 branch field then a jump/branch to that chain is made. Jumps
179 can only be made to user defined chains. As described above,
180 when the end of a builtin chain is reached then a default
181 policy is returned. If the end of a used defined chain is
182 reached then we return to the rule from whence we
183 came.
184
185
186 There is a reference counter at the head of each chain which
187 determines the number of references to that chain. The
188 reference count of a chain must be zero before it can be
189 deleted to ensure that no branches are effected. To ensure
190 the builtin chains are never deleted their reference count
191 is initialised to one. Also since no branches to builtin
192 chains can be made, their reference counts are always one.
193 The reference count on user defined chains are initialised
194 to zero and are changed accordingly when rules are inserted,
195 deleted etc.
196
197
198 Multiple jumps to different chains are possible which
199 unfortunately make loops possible. Loop detection is
200 therefore provided. Loops are detected when a packet tries
201 to re-enter a chain it is already traversing. An example of
202 a simple loop that could be created is if we set up two user
203 defined chains called
204
205
206 Rule matched (special branch):
207
208
209 The special labels ''ACCEPT'', ''DENY'',
210 ''REJECT'', ''REDIRECT'', ''MASQ'' or ''RETURN''
211 can be given which specify the immediate fate of the packet
212 as discussed above. If no label is specified then the next
213 rule in the chain is analysed.
214
215
216 Using this last option (no label) an accounting chain can be
217 created. If each of the rules in this accounting chain have
218 no branch or label then the packet will always fall through
219 to the end of the chain and then return to the calling
220 chain. Each rule that matches in the accounting chain will
221 have its byte and packet counters incremented as expected.
222 This accounting chain can be branched to from any other
223 chain (eg input, forward or output chain). This is a very
224 neat way of performing packet accounting.
225
226
227 The firewall administration can be changed via calls to
228 setsockopt(2). The existing rules can be inspected by
229 looking at two files in the ''/proc/net'' directory:
230 ''ip_fwchains'', ''ip_fwnames''. These two files are
231 readable only by root. The current administration related to
232 masqueraded sessions can be found in the file
233 ''ip_masquerade'' in the same directory.
234 !!COMMANDS
235
236
237 Command for changing and setting up chains and rules is
238 ipchains(8) Most commands require some additional
239 data to be passed. A pointer to this data and the length of
240 the data are passed as option value and option length
241 arguments to ''setsockopt''. The following commands are
242 available:
243
244
245 __IP_FW_INSERT__
246
247
248 This command allows a rule to be inserted in a chain at a
249 given position (where 1 is considered the start of the
250 chain). If there is already a rule in that position, it is
251 moved one slot, as are any following rules in that chain.
252 The reference count of any chains referenced by this
253 inserted rule are incremented appropriately. The data passed
254 with this command is an ''ip_fwnew'' structure, defining
255 the position, chain and contents of the new
256 rule.
257
258
259 __IP_FW_DELETE__
260
261
262 Remove the first rule matching the specification from the
263 given chain. The data passed with this command is an
264 ''ip_fwchange'' structure, defining the rule to be
265 deleted and its chain. The reference count of any chains
266 referenced by this deleted rule are decremented
267 appropriately. Note that the fw_mark field is currently
268 ignored in rule comparisons (see the __BUGS__
269 section).
270
271
272 __IP_FW_DELETE_NUM__
273
274
275 Remove a rule from one of the chains at a given rule number
276 (where 1 means the first rule). The data passed with this
277 command is an ''ip_fwdelnum'' structure, defining the
278 rule number of the rule to be deleted and its chain. The
279 reference count of any chains referenced by this deleted
280 rule are decremented appropriately.
281
282
283 __IP_FW_ZERO__
284
285
286 Reset the packet and byte counters in all rules of a chain.
287 The data passed with this command is an ''ip_chainlabel''
288 which defines the chain which is to be operated on. See also
289 the description of the ''/proc/net'' files for a way to
290 atomically list and reset the counters.
291
292
293 __IP_FW_FLUSH__
294
295
296 Remove all rules from a chain. The data passed with this
297 command is an ''ip_chainlabel'' which defines the chain
298 to be operated on.
299
300
301 __IP_FW_REPLACE__
302
303
304 Replace a rule in a chain. The new rule overwrites the rule
305 in the given position. Any chains referenced by the new rule
306 are incremented and chains referenced by the overwritten
307 rule are decremented. The data passed with this command is
308 an ''ip_fwnew'' structure, defining the contents of the
309 new rule, the the chain name and the position of the rule in
310 that chain.
311
312
313 __IP_FW_APPEND__
314
315
316 Insert a rule at the end of one of the chains. The data
317 passed with this command is an ''ip_fwchange'' structure,
318 defining the contents of the new rule and the chain to which
319 it is to be appended. Any chains referenced by this new rule
320 have their refcount incremented.
321
322
323 __IP_FW_MASQ_TIMEOUTS__
324
325
326 Set the timeout values used for masquerading. The data
327 passed with this command is a structure containing three
328 fields of type ''int'', representing the timeout values
329 (in jiffies, 1/HZ second) for TCP sessions, TCP sessions
330 after receiving a FIN packet, and UDP packets, respectively.
331 A timeout value 0 means that the current timeout value of
332 the corresponding entry is preserved.
333
334
335 __IP_FW_CHECK__
336
337
338 Check whether a packet would be accepted, denied, rejected,
339 redirected or masqueraded by a chain. The data passed with
340 this command is an ''ip_fwtest'' structure, defining the
341 packet to be tested and the chain which it is to be test on.
342 Both builtin and user defined chains can be
343 tested.
344
345
346 __IP_FW_CREATECHAIN__
347
348
349 Create a chain. The data passed with this command is an
350 ''ip_chainlabel'' defining the name of the chain to be
351 created. Two chains can not have the same name.
352
353
354 __IP_FW_DELETECHAIN__
355
356
357 Delete a chain. The data passed with this command is an
358 ''ip_chainlabel'' defining the name of the chain to be
359 deleted. The chain must not be referenced by any rule (ie.
360 refcount must be zero). The chain must also be empty which
361 can be achieved using IP_FW_FLUSH.
362
363
364 __IP_FW_POLICY__
365
366
367 Changes the default policy on a builtin rule. The data
368 passed with this command is an ''ip_fwpolicy'' structure,
369 defining the chain whose policy is to be changed and the new
370 policy. The chain must be a builtin chain as user-defined
371 chains don't have default policies.
372 !!STRUCTURES
373
374
375 The ''ip_fw'' structure contains the following relevant
376 fields to be filled in for adding or replacing a
377 rule:
378
379
380 struct in_addr fw_src, fw_dst
381
382
383 Source and destination IP addresses.
384
385
386 struct in_addr fw_smsk, fw_dmsk
387
388
389 Masks for the source and destination IP addresses. Note that
390 a mask of 0.0.0.0 will result in a match for all
391 hosts.
392
393
394 char fw_vianame[[IFNAMSIZ]
395
396
397 Name of the interface via which a packet is received by the
398 system or is going to be sent by the system. If the option
399 __IP_FW_F_WILDIF__ is specified, then the fw_vianame need
400 only match the packet interface up to the first NUL
401 character in fw_vianame. This allows wildcard-like effects.
402 The empty string has a special meaning: it will match with
403 all device names.
404
405
406 __u16 fw_flg
407
408
409 Flags for this rule. The flags for the different options can
410 be bitwise or'ed with each other.
411
412
413 The options are: __IP_FW_F_TCPSYN__ (only matches with
414 TCP packets when the SYN bit is set and both the ACK and RST
415 bits are cleared in the TCP header, invalid with other
416 protocols), The option __IP_FW_F_MARKABS__ is described
417 under the fw_mark entry. The option __IP_FW_F_PRN__ can
418 be used to list some information about a matching packet via
419 ''printk''(). The option __IP_FW_F_FRAG__ can be used
420 to specify a rule which applies only to second and
421 succeeding fragments (initial fragments can be treated like
422 normal packets for the sake of firewalling). Non-fragmented
423 packets and initial fragments will never match such a rule.
424 Fragments do not contain the complete information assumed
425 for most firewall rules, notably ICMP type and code, UDP/TCP
426 port numbers, or TCP SYN or ACK bits. Rules which try to
427 match packets by these criteria will never match a
428 (non-first) fragment. The option __IP_FW_F_NETLINK__ can
429 be specified if the kernel has been compiled with
430 CONFIG_IP_FIREWALL_NETLINK enabled. This means that all
431 matching packets will be sent out the firewall netlink
432 device (character device, major number 36, minor number 3).
433 The output of this device is four bytes indicating the total
434 length, four bytes indicating the mark value of the packet
435 (as described under fw_mark above), a string of IFNAMSIZ
436 characters containing the interface name for the packet, and
437 then the packet itself. The packet is truncated to
438 __fw_outputsize__ bytes if it is longer.
439
440
441 __u16 fw_invflg
442
443
444 This field is a set of flags used to negate the meaning of
445 other fields, eg. to specify that a packet must NOT be on an
446 interface. The valid flags are __IP_FW_INV_SRCIP__
447 (invert the meaning of the fw_src field)
448 __IP_FW_INV_DSTIP__ (invert the meaning of fw_dst)
449 __IP_FW_INV_PROTO__ (invert the meaning of fw_proto)
450 __IP_FW_INV_SRCPT__ (invert the meaning of fw_spts)
451 __IP_FW_INV_DSTPT__ (invert the meaning of fw_dpts)
452 __IP_FW_INV_VIA__ (invert the meaning of fw_vianame)
453 __IP_FW_INV_SYN__ (invert the meaning of fw_flg
454 __IP_FW_INV_FRAG__ (invert the meaning of
455 fw_flg
456 __
457
458
459 __u16 fw_proto
460
461
462 The protocol that this rule applies to. The protocol number
463 0 is used to mean `any protocol'.
464
465
466 __u16 fw_spts[[2], fw_dpts[[2]
467
468
469 These fields specify the range of source ports, and the
470 range of destination ports respectively. The first array
471 element is the inclusive minimum, and the second is the
472 inclusive maximum. Unless the rule specifies a protocol of
473 TCP, UDP or ICMP, the port range must be 0 to 65535. For
474 ICMP, the ''fw_spts'' field is used to check the ICMP
475 type, and the ''fw_dpts'' field is used to check the ICMP
476 code.
477
478
479 __u16 fw_redirpt
480
481
482 This field must be zero unless the target of the rule is
483
484
485 __u32 fw_mark
486
487
488 This field indicates a value to mark the skbuff with (which
489 contains the administration data for the matching packet).
490 This is currently unused, but could be used to control how
491 individual packets are treated. If the
492 __IP_FW_F_MARKABS__ flag is set then the value in
493 ''fw_mark'' simply replaces the current mark in the
494 skbuff, rather than being added to the current mark value
495 which is normally done. To subtract a value, simply use a
496 large number for ''fw_mark'' and 32-bit wrap-around will
497 occur.
498
499
500 __u8 fw_tosand, fw_tosxor
501
502
503 These 8-bit masks define how the TOS field in the IP header
504 should be changed when a packet is accepted by the firewall
505 rule. The TOS field is first bitwise and'ed with
506 ''fw_tosand'' and the result of this will be bitwise
507 xor'ed with ''fw_tosxor''. Obviously, only packets which
508 match the rule have their TOS effected. It is the
509 responsibility of the user that packets with invalid TOS
510 bits are not created using this option.
511
512
513 The ''ip_fwuser'' structure, used when calling some of
514 the above commands contains the following
515 fields:
516
517
518 struct ip_fw ipfw
519
520
521 ''See above''
522
523
524 ip_chainlabel label This is the label of the chain which is
525 to be operated on.
526
527
528 The ''ip_fwpkt'' structure, used when checking a packet,
529 contains the following fields:
530
531
532 struct iphdr fwp_iph
533
534
535 The IP header. See '''' for a detailed
536 description of the ''iphdr'' structure.
537
538
539 struct tcphdr fwp_protoh.fwp_tcph
540 struct udphdr fwp_protoh.fwp_udph
541 struct icmphdr fwp_protoh.fwp_icmph
542
543
544 The TCP, UDP, or ICMP header, combined in a union named
545 ''fwp_protoh''. See '''',
546 '''', or ''''
547 for a detailed description of the respective
548 structures.
549
550
551 struct in_addr fwp_via
552
553
554 The interface address via which the packet is pretended to
555 be received or sent.
556 !!CHANGES
557
558
559 The ability to add in extra chains other than just the
560 standard input, output and forward chains is very powerful.
561 The ability to branch to any chain makes the replication of
562 rules unnecessary. Accounting becomes automatic as a single
563 chain can be referenced by all builtin chains to do the
564 accounting.
565
566
567 Fragments must now be handled explicitly; previously second
568 and succeeding fragments were passed
569 automatically.
570
571
572 The lowest TOS bit (MBZ) could not be effected previously;
573 the kernel used to silently mask out any attempted
574 manipulation of the lowest TOS bit. (``So now you know how
575 to do it - DON'T.'').
576
577
578 The packet and byte counters are now 64-bit on 32-bit
579 machines (actually presented as two 32-bit
580 values).
581
582
583 The ability to specify an interface by an IP address was
584 obsoleted by the ability to specify it by name; the
585 combination of the two was error-prone and so only an
586 interface name can now be used.
587
588
589 The old __IP_FW_F_TCPACK__ flag was made obsolete by the
590 ability to invert the __IP_FW_F_TCPSYN__
591 flag.
592
593
594 The old __IP_FW_F_BIDIR__ flag made the kernel code
595 complex and is no longer supported.
596
597
598 The ability to specify several ports in one rule was messy
599 and didn't win much, so has been removed.
600 !!RETURN VALUE
601
602
603 On success (or a straightforward packet accept for the CHECK
604 options), zero is returned. On error, -1 is returned and
605 ''errno'' is set appropriately. See setsockopt(2)
606 for a list of possible error values. __ENOENT__ indicates
607 that the given chain name doesn't exist. When the check
608 packet command is used, zero is returned when the packet
609 would be accepted without redirection or masquerading.
610 Otherwise, -1 is returned and ''errno'' is set to
611 __ECONNABORTED__ (packet would be accepted using
612 redirection), __ECONNRESET__ (packet would be accepted
613 using masquerading), __ETIMEDOUT__ (packet would be
614 denied), __ECONNREFUSED__ (packet would be rejected),
615 __ELOOP__ (packet got into a loop), __ENFILE__ (packet
616 fell off end of chain; only occurs for user defined
617 chains).
618 !!LISTING RULES
619
620
621 In the directory ''/proc/net'' there are two entries to
622 list the currently defined rules and chains:
623
624
625 ip_fwnames
626
627
628 (for IP firewall chain names) One line per chain. Each line
629 contains the chain name, policy, the number of references to
630 that chain and the packet and byte counters which have
631 matched the policy (represented as two pairs of 32-bit
632 numbers; most significant 32-bits first).
633
634
635 ip_fwchains
636
637
638 (for IP firewall chains) One line per rule; rules are listed
639 one chain at a time (from first to last as they appear in
640 ''/proc/net/ip_fwnames'') and in order from first to last
641 down each chain.
642
643
644 The fields are: the chain name for that rule, source address
645 and mask, destination address and mask, interface name (or
646
647
648 These files may also be opened in read/write mode. In that
649 case, the packet and byte counters in all the rules of that
650 category will be reset to zero after listing their current
651 values.
652
653
654 The file ''/proc/net/ip_masquerade'' contains the kernel
655 administration related to masquerading. After a header line,
656 each masqueraded session is described on a separate line
657 with the following entries, separated by white space or by
658 ':' (the address/port number pairs): protocol name
659 (
660 ''
661 !!FILES
662
663
664 ''/proc/net/ip_fwchains
665 /proc/net/ip_fwnames
666 /proc/net/ip_masquerade''
667 !!BUGS
668
669
670 The setsockopt(2) interface is a crock. This should
671 be put under /proc/sys/net/ipv4 and the world would be a
672 better place.
673
674
675 There is no way to read and reset a single chain; stop
676 packets traversing the chain and then list, reset and
677 restore traffic.
678
679
680 The packet and byte counters should be presented in /proc as
681 a single 64-bit value, not two 32-bit values.
682
683
684 The
685 IP_FW_F_MARKABS__
686 flag is ignored in comparisons.
687 !!SEE ALSO
688
689
690 setsockopt(2), socket(2), ipchains(8)
691 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.