2 .\" Heavily modified by Paul ``Rusty'' Russell March 1997
4 .\" Based on the original ipfwadm man page by Jos Vos <jos@xos.nl> (see README)
6 .\" This program is free software; you can redistribute it and/or modify
7 .\" it under the terms of the GNU General Public License as published by
8 .\" the Free Software Foundation; either version 2 of the License, or
9 .\" (at your option) any later version.
11 .\" This program is distributed in the hope that it will be useful,
12 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 .\" GNU General Public License for more details.
16 .\" You should have received a copy of the GNU General Public License
17 .\" along with this program; if not, write to the Free Software
18 .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21 .TH IPCHAINS 8 "February 8, 1998" "" ""
23 ipchains \- IP firewall administration
25 .BR "ipchains -[ADC] " "chain rule-specification [options]"
27 .BR "ipchains -[RI] " "chain rulenum rule-specification [options]"
29 .BR "ipchains -D " "chain rulenum [options]"
31 .BR "ipchains -[LFZNX] " "[chain] [options]"
33 .BR "ipchains -P " "chain target [options]"
35 .BR "ipchains -M " "[ -L | -S ] [options]"
38 is used to set up, maintain, and inspect the IP firewall rules in the
39 Linux kernel. These rules can be divided into 4 different categories:
40 the IP input chain, the IP output chain, the IP forwarding chain, and
43 For each of these categories, a separate table of rules is maintained,
44 any of which might refer to one of the user-defined chains.
49 A firewall rule specifies criteria for a packet, and a target. If the
50 packet does not match, the next rule in the chain is then examined; if
51 it does match, then the next rule is specified by the value of the
52 target, which can be the name of a user-defined chain, or one of the
63 means to let the packet through.
65 means to drop the packet on the floor.
67 means the same as drop, but is more polite and easier to debug, since
68 an ICMP message is sent back to the sender indicating that the packet
69 was dropped. (Note that
73 are the same for ICMP packets.)
76 is only legal for the forward and user defined chains, and can only be
77 used when the kernel is compiled with
78 .B CONFIG_IP_MASQUERADE
80 With this, packets will be masqueraded as if they originated from the
81 local host. Furthermore, reverse packets will be recognized as such
82 and they will be demasqueraded automatically, bypassing the forwarding
86 is only legal for the input and user-defined chains and can only be
87 used when the Linux kernel is compiled with
88 .B CONFIG_IP_TRANSPARENT_PROXY
90 With this, packets will be redirected to a local socket, even if they
91 were sent to a remote host. If the specified redirection port is 0,
92 which is the default value, the destination port of a packet will be
93 used as the redirection port. When this target is used, an optional
94 extra argument (the port number) can be supplied.
96 If the end of a user-defined chain is reached, or a rule with target
98 is matched, then the next rule in the previous (calling) chain is
99 examined. If the end of a builtin chain is reached, or a rule in a
100 builtin chain with target
102 is matched, the target specified by the chain policy determines the
105 The options that are recognized by
107 can be divided into several different groups.
109 These options specify the specific action to perform; only one of them
110 can be specified on the command line, unless otherwise specified
111 below. For all the long versions of the command and option names, you
112 only need to use enough letters to ensure that
114 can differentiate it from all other options.
117 Append one or more rules to the end of the selected chain.
118 When the source and/or destination names resolve to more than one
119 address, a rule will be added for each possible address combination.
122 Delete one or more rules from the selected chain. There are two
123 versions of this command: the rule can be specified as a number in the
124 chain (starting at 1 for the first rule) or a rule to match.
127 Replace a rule in the selected chain. If the source and/or
128 destination names resolve to multiple addresses, the command will
129 fail. Rules are numbered starting at 1.
132 Insert one or more rules in the selected chain as the given rule
133 number. So, if the rule number is 1, the rule or rules are inserted
134 at the head of the chain.
137 List all rules in the selected chain. If no chain is selected, all
138 chains are listed. It is legal to specify the
140 (zero) option as well, in which case no chain may be specified. The
141 exact output is affected by the other arguments given.
144 Flush the selected chain. This is equivalent to deleting all the
148 Zero the packet and byte counters in all chains. It is legal to
151 (list) option as well, to see the counters immediately before they are
152 cleared; if this is done, then no specific chain can be specified
155 be displayed and cleared).
158 Create a new user-defined chain of the given name. There must be no
159 target of that name already.
161 .B "-X, --delete-chain"
162 Delete the specified user-defined chain. There must be no references
163 to the chain (if there are you must delete or replace the referring
164 rules before the chain can be deleted). If no argument is given, it
165 will attempt to delete every non-builtin chain.
168 Set the policy for the chain to the given target. See the section
170 for the legal targets. Only non-userdefined chains can have policies,
171 and neither built-in nor user-defined chains can be policy targets.
173 .B "-M, --masquerading"
174 This option allows viewing of the currently masqueraded connections
175 (in conjuction with the
177 option) or to set the kernel masquerading parameters (with the
181 .BI "-S, --set tcp tcpfin udp"
182 Change the timeout values used for masquerading.
183 This command always takes 3 parameters, representing the timeout values
184 (in seconds) for TCP sessions, TCP sessions after receiving
185 a FIN packet, and UDP packets, respectively.
186 A timeout value 0 means that the current timeout value of the
187 corresponding entry is preserved.
188 This option is only allowed in combination with the
193 Check the given packet against the selected chain. This is extremely
194 useful for testing, as the same kernel routines used to check "real"
195 network packets are used to check this packet. It can be used to
196 check user-defined chains as well as the builtin ones. The
197 same arguments used to specify firewall rules are used to construct
198 the packet to be tested. In particular, the
206 (interface) flags are compulsory.
209 Give a (currently very brief) description of the command syntax. If followed by the word
211 then a list of ICMP names is listed.
214 Simply output the ipchains version number.
216 The following parameters make up a rule specification (as used in the
217 add, delete, replace, append and check commands).
219 .BI "-p, --protocol" "[!] protocol"
220 The protocol of the rule or of the packet to check.
221 The specified protocol can be one of
227 or it can be a numeric value, representing one of these protocols or a
228 different one. Also a protocol name from /etc/protocols is allowed.
229 A "!" argument before the protocol inverts the
230 test. The number zero is equivalent to
234 will match with all protocols and is taken as default when this
237 may not be used in in combination with the check command.
239 .BR "-s, --source, --src " "[!] \fIaddress\fP[/\fImask\fP] [!] [\fIport[:port]\fP]"
240 Source specification.
242 can be either a hostname, a network name, or a plain IP address.
245 can be either a network mask or a plain number,
246 specifying the number of 1's at the left side of the network mask.
251 A "!" argument before the address specification inverts the sense of
254 The source may include a port specification or ICMP type. This can
255 either be a service name, a port number, a numeric ICMP type, or one
256 of the ICMP type names shown by the command
260 Note that many of these ICMP names refer to both a type and code,
261 meaning that an ICMP code after the
263 flag is illegal. In the rest of this paragraph, a
265 means either a port specification or an ICMP type.
266 An inclusive range can also be specified, using the format
268 If the first port is omitted, "0" is assumed; if the last is omitted,
271 Ports may only be specified in combination with the
276 protocols. A "!" before the port specification inverts the sense.
277 When the check command is specified, exactly one port is required, and
280 (fragment) flag is specified, no ports are allowed.
282 .BR "--source-port " "[!] [\fIport[:port]\fP]"
283 This allows separate specification of the source port or port range.
284 See the description of the
286 flag above for details.The flag
288 is an alias for this option.
290 .BR "-d, --destination, --dst " "[!] \fIaddress\fP[/\fImask\fP] [!] [\fIport[:port]\fP]"
291 Destination specification.
292 See the desciption of the
294 (source) flag for a detailed description of the syntax. For ICMP,
295 which does not have ports, a "destination port" refers to the numeric
298 .BR "--destination-port " "[!] [\fIport[:port]\fP]"
299 This allows separate specification of the ports. See the description of
302 flag for details. The flag
304 is an alias for this option.
306 .BR "--icmp-type " "[!] typename"
307 This allows specification of the ICMP type (use the
309 option to see valid ICMP type names). This is often more convenient
310 than appending it to the destination specification.
312 .BR "-j, --jump " "\fItarget\fP"
313 This specifies the target of the rule; ie. what to do if the packet
314 matches it. The target can be a user-defined chain (not the one this
315 rule is in) or one of the special targets which decide the fate of the
316 packet immediately. If this option is omitted in a rule, then
317 matching the rule will have no effect on the packet's fate, but the
318 counters on the rule will be incremented.
320 .BI "-i, --interface " "[!] name"
321 Optional name of an interface via which a packet is received (for
322 packets entering the input chain), or via which is packet is going to
323 be sent (for packets entering the forward or output chains). When
324 this option is omitted, the empty string is assumed, which has a
325 special meaning and will match with any interface name. When the "!"
326 argument is used before the interface name, the sense is inverted. If
327 the interface name ends in a "+", then any interface which begins with
328 this name will match.
330 .B "[!] " "-f, --fragment"
331 This means that the rule only refers to second and further fragments
332 of fragmented packets. Since there is no way to tell the source or
333 destination ports of such a packet (or ICMP type), such a packet will
334 not match any rules which specify them. When the "!" argument
335 precedes the "-f" flag, the sense is inverted.
337 The following additional options can be specified:
339 .BI "-b, --bidirectional"
340 Bidirectional mode. The rule will match with IP packets in both
341 directions; this has the same effect as repeating the rule with the
342 source & destination reversed. Note that this does NOT mean that if
343 you allow TCP syn packets out, the -b rule will allow non-SYN packets
344 back in: the reverse rule is exactly the same as the rule you entered.
345 This means that it's usually better to simply avoid the -b flag and
346 spell the rules out explicitly.
349 Verbose output. This option makes the list command show the interface
350 address, the rule options (if any), and the TOS masks. The packet and
351 byte counters are also listed, with the suffix 'K', 'M' or 'G' for
352 1000, 1,000,000 and 1,000,000,000 multipliers respectively (but see
355 flag to change this). When used in combination with
357 information related to delta sequence numbers will also be listed.
358 For appending, insertion, deletion and replacement, this causes
359 detailed information on the rule or rules to be printed.
363 IP addresses and port numbers will be printed in numeric format.
364 By default, the program will try to display them as host names,
365 network names, or services (whenever applicable).
368 Turn on kernel logging of matching packets.
369 When this option is set for a rule, the Linux kernel will print
371 of all matching packets (like most IP header fields) via
374 .BI "-o, --output" " [maxsize]"
375 Copy matching packets to the userspace device. This is currently
376 mainly for developers who want to play with firewalling effects in
377 userspace. The optional maxsize argument can be used to limit the
378 maximum number of bytes from the packet which are to be copied. This
379 option is only valid if the kernel has been compiled with
380 CONFIG_IP_FIREWALL_NETLINK set.
382 .BI "-m, --mark" " markvalue"
383 Mark matching packets. Packets can be marked with a 32-bit unsigned
384 value which may (one day) change how they are handled internally. If
385 you are not a kernel hacker you are unlikely to care about this. If
388 begins with a + or -, then this value will be added or subtracted from
389 the current marked value of the packet (which starts at zero).
391 .BI "-t, --TOS" " andmask xormask"
392 Masks used for modifying the TOS field in the IP header. When a
393 packet matches a rule, its TOS field is first bitwise and'ed with
394 first mask and the result of this will be bitwise xor'ed with the
395 second mask. The masks should be specified as hexadecimal 8-bit
396 values. As the LSB of the TOS field must be unaltered (RFC 1349), TOS
397 values which would cause it to be altered are rejected, as are any
398 rules which always set more than one TOS bit. Rules which might set
399 multiple TOS bits for certain packets result in warnings (sent to
400 stdout) which can be ignored if you know that packets with those TOS
401 values will never reach that rule. Obviously,
402 manipulating the TOS is a meaningless gesture if the rule's target is
409 Display the exact value of the packet and byte counters,
410 instead of only the rounded number in K's (multiples of 1000)
411 M's (multiples of 1000K) or G's (multiples of 1000M). This option is
412 only relevant for the
417 Only match TCP packets with the SYN bit set and the ACK and FIN bits
418 cleared. Such packets are used to request TCP connection initiation;
419 for example, blocking such packets coming in an interface will prevent
420 incoming TCP connections, but outgoing TCP connections will be
421 unaffected. This option is only meaningful when the protocol type is
422 set to TCP. If the "!" flag precedes the "-y", the sense of the
426 When listing rules, add line numbers to the beginning of each rule,
427 corresponding to that rule's position in the chain.
430 Disable all warnings.
432 .I /proc/net/ip_fwchains
434 .I /proc/net/ip_masquerade
436 Various error messages are printed to standard error. The exit code
437 is 0 for correct functioning. Errors which appear to be caused by
438 invalid or abused command line parameters cause an exit code of 2, and
439 other errors cause an exit code of 1.
442 If input is a terminal, and a rule is inserted in, or appended to, the
443 forward chain, and IP forwarding does not seem to be enabled, and
444 --no-warnings is not specified, a message is printed to standard
445 output, warning that no forwarding will occur until this is rectified.
446 This is to help users unaware of the requirement (which did not exist
449 There is no way to reset the packet and byte counters in one chain
450 only. This is a kernel limitation.
452 Loop detection is not done in ipchains; packets in a loop get dropped
453 and logged, but that's the first you'll find out about it if you
454 inadvertantly create a loop.
456 The explanation of what effect marking a packet has is intentionally
457 vague until documentation describing the new 2.1 kernel's packet
458 scheduling routines is released.
460 There is no way to zero the policy counters (ie. those on the built-in
465 is very different from the ipfwadm by Jos Vos, as it uses the new IP
466 firewall trees. Its functionality is a superset of ipfwadm, and there
467 is generally a 1:1 mapping of commands. I believe the new command
468 names are more rational. There are, however, a few changes of which
471 Fragments are handled differently. All fragments after the first used
472 to be let through (which is usually safe); they can now be filtered.
473 This means that you should probably add an explicit rule to accept
474 fragments if you are converting over. Also, look for old accounting
475 rules which check for source and destination ports of 0xFFFF (0xFF for
476 ICMP packets) which was the old way of doing accounting on fragments.
478 Accounting rules are now simply integrated into the input and output
479 chains; you can simulate the old behaviour like so:
487 ipchains -I input -j acctio
489 ipchains -I input -j acctin
491 ipchains -I output -j acctio
493 ipchains -I output -j acctout
495 This creates three user-defined chains,
500 which are to contain any accounting rules (these rules should be
503 flag, so that the packets simply pass through them unscathed).
509 target encountered by the kernel out of place (ie. not
510 during a forward or input rule respectively) will cause a message to
511 the syslog and the packet to be dropped.
513 The old behaviour of SYN and ACK matching (which was previously
514 ignored for non-TCP packets) has changed; the SYN option is not valid
515 for non-TCP-specific rules.
517 The ACK matching option (the
519 flag) is no longer supported; the combination of
523 will give the equivalent).
525 It is now illegal to specify a TOS mask which will set or alter the
526 least significant TOS bit; previously TOS masks were silently altered
527 by the kernel if they tried to do this.
531 flag is now handled by simply inserting or deleting a pair of rules,
532 one with the source and destination specifications reversed.
534 There is no way to specify an interface by address: use its name.
538 Rusty Russell <rusty@linuxcare.com>. Thanks also to Hans Persson for
539 detailed proofreading; I want him to read all my future documents!