Penguin
Recent Changes
Annotated edit history of ipchains(8) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 IPCHAINS
2 !!!IPCHAINS
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 TARGETS
7 OPTIONS
8 FILES
9 DIAGNOSTICS
10 BUGS
11 NOTES
12 SEE ALSO
13 AUTHOR
14 ----
15 !!NAME
16
17
18 ipchains - IP firewall administration
19 !!SYNOPSIS
20
21
22 __ipchains -[[ADC]__ chain rule-specification
23 [[options]__
24 ipchains -[[RI]__ chain rulenum rule-specification
25 [[options]__
26 ipchains -D__ chain rulenum [[options]__
27 ipchains -[[LFZNX]__ [[chain] [[options]__
28 ipchains -P__ chain target [[options]__
29 ipchains -M__ [[ -L | -S ] [[options]
30 !!DESCRIPTION
31
32
33 __Ipchains__ is used to set up, maintain, and inspect the
34 IP firewall rules in the Linux kernel. These rules can be
35 divided into 4 different categories: the IP input chain, the
36 IP output chain, the IP forwarding chain, and user defined
37 chains.
38
39
40 For each of these categories, a separate table of rules is
41 maintained, any of which might refer to one of the
42 user-defined chains. See ipfw(4) for more
43 details.
44 !!TARGETS
45
46
47 A firewall rule specifies criteria for a packet, and a
48 target. If the packet does not match, the next rule in the
49 chain is then examined; if it does match, then the next rule
50 is specified by the value of the target, which can be the
51 name of a user-defined chain, or one of the special values
52 ''ACCEPT'', ''DENY'', ''REJECT'', ''MASQ'',
53 ''REDIRECT'', or ''RETURN''.
54
55
56 ''ACCEPT'' means to let the packet through. ''DENY''
57 means to drop the packet on the floor. ''REJECT'' means
58 the same as drop, but is more polite and easier to debug,
59 since an ICMP message is sent back to the sender indicating
60 that the packet was dropped. (Note that ''DENY'' and
61 ''REJECT'' are the same for ICMP packets.)
62
63
64 ''MASQ'' is only legal for the forward and user defined
65 chains, and can only be used when the kernel is compiled
66 with __CONFIG_IP_MASQUERADE__ defined. With this, packets
67 will be masqueraded as if they originated from the local
68 host. Furthermore, reverse packets will be recognized as
69 such and they will be demasqueraded automatically, bypassing
70 the forwarding chain.
71
72
73 ''REDIRECT'' is only legal for the input and user-defined
74 chains and can only be used when the Linux kernel is
75 compiled with __CONFIG_IP_TRANSPARENT_PROXY__ defined.
76 With this, packets will be redirected to a local socket,
77 even if they were sent to a remote host. If the specified
78 redirection port is 0, which is the default value, the
79 destination port of a packet will be used as the redirection
80 port. When this target is used, an optional extra argument
81 (the port number) can be supplied.
82
83
84 If the end of a user-defined chain is reached, or a rule
85 with target ''RETURN'' is matched, then the next rule in
86 the previous (calling) chain is examined. If the end of a
87 builtin chain is reached, or a rule in a builtin chain with
88 target ''RETURN'' is matched, the target specified by the
89 chain policy determines the fate of the packet.
90 !!OPTIONS
91
92
93 The options that are recognized by __ipchains__ can be
94 divided into several different groups.
95
96
97 __COMMANDS__
98
99
100 These options specify the specific action to perform; only
101 one of them can be specified on the command line, unless
102 otherwise specified below. For all the long versions of the
103 command and option names, you only need to use enough
104 letters to ensure that __ipchains__ can differentiate it
105 from all other options.
106
107
108 __-A, --append__
109
110
111 Append one or more rules to the end of the selected chain.
112 When the source and/or destination names resolve to more
113 than one address, a rule will be added for each possible
114 address combination.
115
116
117 __-D, --delete__
118
119
120 Delete one or more rules from the selected chain. There are
121 two versions of this command: the rule can be specified as a
122 number in the chain (starting at 1 for the first rule) or a
123 rule to match.
124
125
126 __-R, --replace__
127
128
129 Replace a rule in the selected chain. If the source and/or
130 destination names resolve to multiple addresses, the command
131 will fail. Rules are numbered starting at 1.
132
133
134 __-I, --insert__
135
136
137 Insert one or more rules in the selected chain as the given
138 rule number. So, if the rule number is 1, the rule or rules
139 are inserted at the head of the chain.
140
141
142 __-L, --list__
143
144
145 List all rules in the selected chain. If no chain is
146 selected, all chains are listed. It is legal to specify the
147 __-Z__ (zero) option as well, in which case no chain may
148 be specified. The exact output is affected by the other
149 arguments given.
150
151
152 __-F, --flush__
153
154
155 Flush the selected chain. This is equivalent to deleting all
156 the rules one by one.
157
158
159 __-Z, --zero__
160
161
162 Zero the packet and byte counters in all chains. It is legal
163 to specify the __-L, --list__ (list) option as well, to
164 see the counters immediately before they are cleared; if
165 this is done, then no specific chain can be specified (they
166 will ''all'' be displayed and cleared).
167
168
169 __-N, --new-chain__
170
171
172 Create a new user-defined chain of the given name. There
173 must be no target of that name already.
174
175
176 __-X, --delete-chain__
177
178
179 Delete the specified user-defined chain. There must be no
180 references to the chain (if there are you must delete or
181 replace the referring rules before the chain can be
182 deleted). If no argument is given, it will attempt to delete
183 every non-builtin chain.
184
185
186 __-P, --policy__
187
188
189 Set the policy for the chain to the given target. See the
190 section __TARGETS__ for the legal targets. Only
191 non-userdefined chains can have policies, and neither
192 built-in nor user-defined chains can be policy
193 targets.
194
195
196 __-M, --masquerading__
197
198
199 This option allows viewing of the currently masqueraded
200 connections (in conjuction with the __-L__ option) or to
201 set the kernel masquerading parameters (with the __-S__
202 option).
203
204
205 __-S, --set tcp tcpfin udp__
206
207
208 Change the timeout values used for masquerading. This
209 command always takes 3 parameters, representing the timeout
210 values (in seconds) for TCP sessions, TCP sessions after
211 receiving a FIN packet, and UDP packets, respectively. A
212 timeout value 0 means that the current timeout value of the
213 corresponding entry is preserved. This option is only
214 allowed in combination with the __-M__ flag.
215
216
217 __-C, --check__
218
219
220 Check the given packet against the selected chain. This is
221 extremely useful for testing, as the same kernel routines
222 used to check
223 -s__ (source),
224 __-d__ (destination), __-p__ (protocol), and __-i__
225 (interface) flags are compulsory.
226
227
228 __-h, --help__
229
230
231 Give a (currently very brief) description of the command
232 syntax. If followed by the word ''icmp'', then a list of
233 ICMP names is listed.
234
235
236 __-V, --version__
237
238
239 Simply output the ipchains version number.
240
241
242 __PARAMETERS__
243
244
245 The following parameters make up a rule specification (as
246 used in the add, delete, replace, append and check
247 commands).
248
249
250 __-p, --protocol__''[[!] protocol''
251
252
253 The protocol of the rule or of the packet to check. The
254 specified protocol can be one of ''tcp'', ''udp'',
255 ''icmp'', or ''all'', or it can be a numeric value,
256 representing one of these protocols or a different one. Also
257 a protocol name from /etc/protocols is allowed. A
258 ''all''. Protocol
259 ''all'' will match with all protocols and is taken as
260 default when this option is omitted. ''All'' may not be
261 used in in combination with the check command.
262
263
264 __-s, --source, --src__ [[!] ''address''[[/''mask'']
265 [[!] [[''port[[:port]'']
266
267
268 Source specification. ''Address'' can be either a
269 hostname, a network name, or a plain IP address. The
270 ''mask'' can be either a network mask or a plain number,
271 specifying the number of 1's at the left side of the network
272 mask. Thus, a mask of ''24'' is equivalent to
273 ''255.255.255.0''. A
274 ''
275
276
277 The source may include a port specification or ICMP type.
278 This can either be a service name, a port number, a numeric
279 ICMP type, or one of the ICMP type names shown by the
280 command
281 ipchains -h icmp
282 Note that many of these ICMP names refer to both a type and
283 code, meaning that an ICMP code after the __-d__ flag is
284 illegal. In the rest of this paragraph, a ''port'' means
285 either a port specification or an ICMP type. An inclusive
286 range can also be specified, using the format
287 ''port'':''port''. If the first port is omitted,
288 ''
289
290
291 Ports may only be specified in combination with the
292 ''tcp'', ''udp'', or ''icmp'' protocols. A
293 ''-f__ (fragment) flag is
294 specified, no ports are allowed.
295
296
297 __--source-port__ [[!] [[''port[[:port]'']
298
299
300 This allows separate specification of the source port or
301 port range. See the description of the __-s__ flag above
302 for details.The flag __--sport__ is an alias for this
303 option.
304
305
306 __-d, --destination, --dst__ [[!]
307 ''address''[[/''mask''] [[!]
308 [[''port[[:port]'']
309
310
311 Destination specification. See the desciption of the
312 __-s__ (source) flag for a detailed description of the
313 syntax. For ICMP, which does not have ports, a
314 __
315
316
317 __--destination-port__ [[!]
318 [[''port[[:port]'']
319
320
321 This allows separate specification of the ports. See the
322 description of the __-s__ flag for details. The flag
323 __--dport__ is an alias for this option.
324
325
326 __--icmp-type__ [[!] typename
327
328
329 This allows specification of the ICMP type (use the __-h
330 icmp__ option to see valid ICMP type names). This is often
331 more convenient than appending it to the destination
332 specification.
333
334
335 __-j, --jump__ ''target''
336
337
338 This specifies the target of the rule; ie. what to do if the
339 packet matches it. The target can be a user-defined chain
340 (not the one this rule is in) or one of the special targets
341 which decide the fate of the packet immediately. If this
342 option is omitted in a rule, then matching the rule will
343 have no effect on the packet's fate, but the counters on the
344 rule will be incremented.
345
346
347 __-i, --interface__ ''[[!] name''
348
349
350 Optional name of an interface via which a packet is received
351 (for packets entering the input chain), or via which is
352 packet is going to be sent (for packets entering the forward
353 or output chains). When this option is omitted, the empty
354 string is assumed, which has a special meaning and will
355 match with any interface name. When the
356
357
358 __[[!] -f, --fragment__
359
360
361 This means that the rule only refers to second and further
362 fragments of fragmented packets. Since there is no way to
363 tell the source or destination ports of such a packet (or
364 ICMP type), such a packet will not match any rules which
365 specify them. When the
366
367
368 __OTHER OPTIONS__
369
370
371 The following additional options can be
372 specified:
373
374
375 __-b, --bidirectional__
376
377
378 Bidirectional mode. The rule will match with IP packets in
379 both directions; this has the same effect as repeating the
380 rule with the source
381
382
383 __-v, --verbose__
384
385
386 Verbose output. This option makes the list command show the
387 interface address, the rule options (if any), and the TOS
388 masks. The packet and byte counters are also listed, with
389 the suffix 'K', 'M' or 'G' for 1000, 1,000,000 and
390 1,000,000,000 multipliers respectively (but see the
391 __-x__ flag to change this). When used in combination
392 with __-M__, information related to delta sequence
393 numbers will also be listed. For appending, insertion,
394 deletion and replacement, this causes detailed information
395 on the rule or rules to be printed.
396
397
398 __-n, --numeric__
399
400
401 Numeric output. IP addresses and port numbers will be
402 printed in numeric format. By default, the program will try
403 to display them as host names, network names, or services
404 (whenever applicable).
405
406
407 __-l, --log__
408
409
410 Turn on kernel logging of matching packets. When this option
411 is set for a rule, the Linux kernel will print some
412 information of all matching packets (like most IP header
413 fields) via ''printk''().
414
415
416 __-o, --output__ ''[[maxsize]''
417
418
419 Copy matching packets to the userspace device. This is
420 currently mainly for developers who want to play with
421 firewalling effects in userspace. The optional maxsize
422 argument can be used to limit the maximum number of bytes
423 from the packet which are to be copied. This option is only
424 valid if the kernel has been compiled with
425 CONFIG_IP_FIREWALL_NETLINK set.
426
427
428 __-m, --mark__ ''markvalue''
429
430
431 Mark matching packets. Packets can be marked with a 32-bit
432 unsigned value which may (one day) change how they are
433 handled internally. If you are not a kernel hacker you are
434 unlikely to care about this. If the string ''markvalue''
435 begins with a + or -, then this value will be added or
436 subtracted from the current marked value of the packet
437 (which starts at zero).
438
439
440 __-t, --TOS__ ''andmask xormask''
441
442
443 Masks used for modifying the TOS field in the IP header.
444 When a packet matches a rule, its TOS field is first bitwise
445 and'ed with first mask and the result of this will be
446 bitwise xor'ed with the second mask. The masks should be
447 specified as hexadecimal 8-bit values. As the LSB of the TOS
448 field must be unaltered (RFC 1349), TOS values which would
449 cause it to be altered are rejected, as are any rules which
450 always set more than one TOS bit. Rules which might set
451 multiple TOS bits for certain packets result in warnings
452 (sent to stdout) which can be ignored if you know that
453 packets with those TOS values will never reach that rule.
454 Obviously, manipulating the TOS is a meaningless gesture if
455 the rule's target is ''DENY'' or
456 ''REJECT''.
457
458
459 __-x, --exact__
460
461
462 Expand numbers. Display the exact value of the packet and
463 byte counters, instead of only the rounded number in K's
464 (multiples of 1000) M's (multiples of 1000K) or G's
465 (multiples of 1000M). This option is only relevant for the
466 __-L__ command.
467
468
469 __[[!] -y, --syn__
470
471
472 Only match TCP packets with the SYN bit set and the ACK and
473 FIN bits cleared. Such packets are used to request TCP
474 connection initiation; for example, blocking such packets
475 coming in an interface will prevent incoming TCP
476 connections, but outgoing TCP connections will be
477 unaffected. This option is only meaningful when the protocol
478 type is set to TCP. If the
479
480
481 __--line-numbers__
482
483
484 When listing rules, add line numbers to the beginning of
485 each rule, corresponding to that rule's position in the
486 chain.
487
488
489 __--no-warnings__
490
491
492 Disable all warnings.
493 !!FILES
494
495
496 ''/proc/net/ip_fwchains
497 /proc/net/ip_masquerade''
498 !!DIAGNOSTICS
499
500
501 Various error messages are printed to standard error. The
502 exit code is 0 for correct functioning. Errors which appear
503 to be caused by invalid or abused command line parameters
504 cause an exit code of 2, and other errors cause an exit code
505 of 1.
506 !!BUGS
507
508
509 If input is a terminal, and a rule is inserted in, or
510 appended to, the forward chain, and IP forwarding does not
511 seem to be enabled, and --no-warnings is not specified, a
512 message is printed to standard output, warning that no
513 forwarding will occur until this is rectified. This is to
514 help users unaware of the requirement (which did not exist
515 in the 2.0 kernels).
516
517
518 There is no way to reset the packet and byte counters in one
519 chain only. This is a kernel limitation.
520
521
522 Loop detection is not done in ipchains; packets in a loop
523 get dropped and logged, but that's the first you'll find out
524 about it if you inadvertantly create a loop.
525
526
527 The explanation of what effect marking a packet has is
528 intentionally vague until documentation describing the new
529 2.1 kernel's packet scheduling routines is
530 released.
531
532
533 There is no way to zero the policy counters (ie. those on
534 the built-in chains).
535 !!NOTES
536
537
538 This __ipchains__ is very different from the ipfwadm by
539 Jos Vos, as it uses the new IP firewall trees. Its
540 functionality is a superset of ipfwadm, and there is
541 generally a 1:1 mapping of commands. I believe the new
542 command names are more rational. There are, however, a few
543 changes of which you should be aware.
544
545
546 Fragments are handled differently. All fragments after the
547 first used to be let through (which is usually safe); they
548 can now be filtered. This means that you should probably add
549 an explicit rule to accept fragments if you are converting
550 over. Also, look for old accounting rules which check for
551 source and destination ports of 0xFFFF (0xFF for ICMP
552 packets) which was the old way of doing accounting on
553 fragments.
554
555
556 Accounting rules are now simply integrated into the input
557 and output chains; you can simulate the old behaviour like
558 so:
559 ipchains -N acctin
560 ipchains -N acctout
561 ipchains -N acctio
562 ipchains -I input -j acctio
563 ipchains -I input -j acctin
564 ipchains -I output -j acctio
565 ipchains -I output -j acctout
566 This creates three user-defined chains, ''acctin'',
567 ''acctout'' and ''acctio'', which are to contain any
568 accounting rules (these rules should be specified without a
569 __-j__ flag, so that the packets simply pass through them
570 unscathed).
571
572
573 A ''MASQ'' or ''REDIRECT'' target encountered by the
574 kernel out of place (ie. not during a forward or input rule
575 respectively) will cause a message to the syslog and the
576 packet to be dropped.
577
578
579 The old behaviour of SYN and ACK matching (which was
580 previously ignored for non-TCP packets) has changed; the SYN
581 option is not valid for non-TCP-specific rules.
582
583
584 The ACK matching option (the __-k__ flag) is no longer
585 supported; the combination of __!__ and __-y__ will
586 give the equivalent).
587
588
589 It is now illegal to specify a TOS mask which will set or
590 alter the least significant TOS bit; previously TOS masks
591 were silently altered by the kernel if they tried to do
592 this.
593
594
595 The __-b__ flag is now handled by simply inserting or
596 deleting a pair of rules, one with the source and
597 destination specifications reversed.
598
599
600 There is no way to specify an interface by address: use its
601 name.
602 !!SEE ALSO
603
604
605 ipfw_chains(4), ipchains-save(8),
606 ipchains-restore(8)
607 !!AUTHOR
608
609
610 Rusty Russell. Thanks also to Hans Persson for detailed
611 proofreading; I want him to read all my future
612 documents!
613 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.