iptables.8.in

   1 .TH IPTABLES 8 "Mar 09, 2002" "" ""
   2 .\"
   3 .\" Man page written by Herve Eychenne <rv@wallfire.org> (May 1999)
   4 .\" It is based on ipchains page.
   5 .\" TODO: add a word for protocol helpers (FTP, IRC, SNMP-ALG)
   6 .\"
   7 .\" ipchains page by Paul ``Rusty'' Russell March 1997
   8 .\" Based on the original ipfwadm man page by Jos Vos <jos@xos.nl>
   9 .\"
  10 .\"     This program is free software; you can redistribute it and/or modify
  11 .\"     it under the terms of the GNU General Public License as published by
  12 .\"     the Free Software Foundation; either version 2 of the License, or
  13 .\"     (at your option) any later version.
  14 .\"
  15 .\"     This program is distributed in the hope that it will be useful,
  16 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\"     GNU General Public License for more details.
  19 .\"
  20 .\"     You should have received a copy of the GNU General Public License
  21 .\"     along with this program; if not, write to the Free Software
  22 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  23 .\"
  24 .\"
  25 .SH NAME
  26 iptables \- administration tool for IPv4 packet filtering and NAT
  27 .SH SYNOPSIS
  28 .BR "iptables [-t table] -[AD] " "chain rule-specification [options]"
  29 .br
  30 .BR "iptables [-t table] -I " "chain [rulenum] rule-specification [options]"
  31 .br
  32 .BR "iptables [-t table] -R " "chain rulenum rule-specification [options]"
  33 .br
  34 .BR "iptables [-t table] -D " "chain rulenum [options]"
  35 .br
  36 .BR "iptables [-t table] -[LFZ] " "[chain] [options]"
  37 .br
  38 .BR "iptables [-t table] -N " "chain"
  39 .br
  40 .BR "iptables [-t table] -X " "[chain]"
  41 .br
  42 .BR "iptables [-t table] -P " "chain target [options]"
  43 .br
  44 .BR "iptables [-t table] -E " "old-chain-name new-chain-name"
  45 .SH DESCRIPTION
  46 .B Iptables
  47 is used to set up, maintain, and inspect the tables of IP packet
  48 filter rules in the Linux kernel.  Several different tables
  49 may be defined.  Each table contains a number of built-in
  50 chains and may also contain user-defined chains.
  51
  52 Each chain is a list of rules which can match a set of packets.  Each
  53 rule specifies what to do with a packet that matches.  This is called
  54 a `target', which may be a jump to a user-defined chain in the same
  55 table.
  56
  57 .SH TARGETS
  58 A firewall rule specifies criteria for a packet, and a target.  If the
  59 packet does not match, the next rule in the chain is the examined; if
  60 it does match, then the next rule is specified by the value of the
  61 target, which can be the name of a user-defined chain or one of the
  62 special values
  63 .IR ACCEPT ,
  64 .IR DROP ,
  65 .IR QUEUE ,
  66 or
  67 .IR RETURN .
  68 .PP
  69 .I ACCEPT
  70 means to let the packet through.
  71 .I DROP
  72 means to drop the packet on the floor.
  73 .I QUEUE
  74 means to pass the packet to userspace (if supported by the kernel).
  75 .I RETURN
  76 means stop traversing this chain and resume at the next rule in the
  77 previous (calling) chain.  If the end of a built-in chain is reached
  78 or a rule in a built-in chain with target
  79 .I RETURN
  80 is matched, the target specified by the chain policy determines the
  81 fate of the packet.
  82 .SH TABLES
  83 There are currently three independent tables (which tables are present
  84 at any time depends on the kernel configuration options and which
  85 modules are present).
  86 .TP
  87 .BI "-t, --table " "table"
  88 This option specifies the packet matching table which the command
  89 should operate on.  If the kernel is configured with automatic module
  90 loading, an attempt will be made to load the appropriate module for
  91 that table if it is not already there.
  92
  93 The tables are as follows:
  94 .RS
  95 .TP .4i
  96 .BR "filter" :
  97 This is the default table (if no -t option is passed).  It contains
  98 the built-in chains
  99 .B INPUT
 100 (for packets destined to local sockets),
 101 .B FORWARD
 102 (for packets being routed through the box), and
 103 .B OUTPUT
 104 (for locally-generated packets).
 105 .TP
 106 .BR "nat" :
 107 This table is consulted when a packet that creates a new
 108 connection is encountered.  It consists of three built-ins:
 109 .B PREROUTING
 110 (for altering packets as soon as they come in),
 111 .B OUTPUT
 112 (for altering locally-generated packets before routing), and
 113 .B POSTROUTING
 114 (for altering packets as they are about to go out).
 115 .TP
 116 .BR "mangle" :
 117 This table is used for specialized packet alteration.  Until kernel
 118 2.4.17 it had two built-in chains:
 119 .B PREROUTING
 120 (for altering incoming packets before routing) and
 121 .B OUTPUT
 122 (for altering locally-generated packets before routing).
 123 Since kernel 2.4.18, three other built-in chains are also supported:
 124 .B INPUT
 125 (for packets coming into the box itself),
 126 .B FORWARD
 127 (for altering packets being routed through the box), and
 128 .B POSTROUTING
 129 (for altering packets as they are about to go out).
 130 .TP
 131 .BR "raw" :
 132 This table is used mainly for configuring exemptions from connection
 133 tracking in combination with the NOTRACK target.  It registers at the netfilter
 134 hooks with higher priority and is thus called before ip_conntrack, or any other
 135 IP tables.  It provides the following built-in chains:
 136 .B PREROUTING
 137 (for packets arriving via any network interface)
 138 .B OUTPUT
 139 (for packets generated by local processes)
 140 .RE
 141 .SH OPTIONS
 142 The options that are recognized by
 143 .B iptables
 144 can be divided into several different groups.
 145 .SS COMMANDS
 146 These options specify the specific action to perform.  Only one of them
 147 can be specified on the command line unless otherwise specified
 148 below.  For all the long versions of the command and option names, you
 149 need to use only enough letters to ensure that
 150 .B iptables
 151 can differentiate it from all other options.
 152 .TP
 153 .BI "-A, --append " "chain rule-specification"
 154 Append one or more rules to the end of the selected chain.
 155 When the source and/or destination names resolve to more than one
 156 address, a rule will be added for each possible address combination.
 157 .TP
 158 .BI "-D, --delete " "chain rule-specification"
 159 .ns
 160 .TP
 161 .BI "-D, --delete " "chain rulenum"
 162 Delete one or more rules from the selected chain.  There are two
 163 versions of this command: the rule can be specified as a number in the
 164 chain (starting at 1 for the first rule) or a rule to match.
 165 .TP
 166 .BR "-I, --insert " "\fIchain\fP [\fIrulenum\fP] \fIrule-specification\fP"
 167 Insert one or more rules in the selected chain as the given rule
 168 number.  So, if the rule number is 1, the rule or rules are inserted
 169 at the head of the chain.  This is also the default if no rule number
 170 is specified.
 171 .TP
 172 .BI "-R, --replace " "chain rulenum rule-specification"
 173 Replace a rule in the selected chain.  If the source and/or
 174 destination names resolve to multiple addresses, the command will
 175 fail.  Rules are numbered starting at 1.
 176 .TP
 177 .BR "-L, --list " "[\fIchain\fP]"
 178 List all rules in the selected chain.  If no chain is selected, all
 179 chains are listed.  As every other iptables command, it applies to the
 180 specified table (filter is the default), so NAT rules get listed by
 181 .nf
 182  iptables -t nat -n -L
 183 .fi
 184 Please note that it is often used with the
 185 .B -n
 186 option, in order to avoid long reverse DNS lookups.
 187 It is legal to specify the
 188 .B -Z
 189 (zero) option as well, in which case the chain(s) will be atomically
 190 listed and zeroed.  The exact output is affected by the other
 191 arguments given. The exact rules are suppressed until you use
 192 .nf
 193  iptables -L -v
 194 .fi
 195 .TP
 196 .BR "-F, --flush " "[\fIchain\fP]"
 197 Flush the selected chain (all the chains in the table if none is given).
 198 This is equivalent to deleting all the rules one by one.
 199 .TP
 200 .BR "-Z, --zero " "[\fIchain\fP]"
 201 Zero the packet and byte counters in all chains.  It is legal to
 202 specify the
 203 .B "-L, --list"
 204 (list) option as well, to see the counters immediately before they are
 205 cleared. (See above.)
 206 .TP
 207 .BI "-N, --new-chain " "chain"
 208 Create a new user-defined chain by the given name.  There must be no
 209 target of that name already.
 210 .TP
 211 .BR "-X, --delete-chain " "[\fIchain\fP]"
 212 Delete the optional user-defined chain specified.  There must be no references
 213 to the chain.  If there are, you must delete or replace the referring
 214 rules before the chain can be deleted.  If no argument is given, it
 215 will attempt to delete every non-builtin chain in the table.
 216 .TP
 217 .BI "-P, --policy " "chain target"
 218 Set the policy for the chain to the given target.  See the section
 219 .B TARGETS
 220 for the legal targets.  Only built-in (non-user-defined) chains can have
 221 policies, and neither built-in nor user-defined chains can be policy
 222 targets.
 223 .TP
 224 .BI "-E, --rename-chain " "old-chain new-chain"
 225 Rename the user specified chain to the user supplied name.  This is
 226 cosmetic, and has no effect on the structure of the table.
 227 .TP
 228 .B -h
 229 Help.
 230 Give a (currently very brief) description of the command syntax.
 231 .SS PARAMETERS
 232 The following parameters make up a rule specification (as used in the
 233 add, delete, insert, replace and append commands).
 234 .TP
 235 .BR "-p, --protocol " "[!] \fIprotocol\fP"
 236 The protocol of the rule or of the packet to check.
 237 The specified protocol can be one of
 238 .IR tcp ,
 239 .IR udp ,
 240 .IR icmp ,
 241 or
 242 .IR all ,
 243 or it can be a numeric value, representing one of these protocols or a
 244 different one.  A protocol name from /etc/protocols is also allowed.
 245 A "!" argument before the protocol inverts the
 246 test.  The number zero is equivalent to
 247 .IR all .
 248 Protocol
 249 .I all
 250 will match with all protocols and is taken as default when this
 251 option is omitted.
 252 .TP
 253 .BR "-s, --source " "[!] \fIaddress\fP[/\fImask\fP]"
 254 Source specification.
 255 .I Address
 256 can be either a network name, a hostname (please note that specifying
 257 any name to be resolved with a remote query such as DNS is a really bad idea),
 258 a network IP address (with /mask), or a plain IP address.
 259 The
 260 .I mask
 261 can be either a network mask or a plain number,
 262 specifying the number of 1's at the left side of the network mask.
 263 Thus, a mask of
 264 .I 24
 265 is equivalent to
 266 .IR 255.255.255.0 .
 267 A "!" argument before the address specification inverts the sense of
 268 the address. The flag
 269 .B --src
 270 is an alias for this option.
 271 .TP
 272 .BR "-d, --destination " "[!] \fIaddress\fP[/\fImask\fP]"
 273 Destination specification.
 274 See the description of the
 275 .B -s
 276 (source) flag for a detailed description of the syntax.  The flag
 277 .B --dst
 278 is an alias for this option.
 279 .TP
 280 .BI "-j, --jump " "target"
 281 This specifies the target of the rule; i.e., what to do if the packet
 282 matches it.  The target can be a user-defined chain (other than the
 283 one this rule is in), one of the special builtin targets which decide
 284 the fate of the packet immediately, or an extension (see
 285 .B EXTENSIONS
 286 below).  If this
 287 option is omitted in a rule, then matching the rule will have no
 288 effect on the packet's fate, but the counters on the rule will be
 289 incremented.
 290 .TP
 291 .BR "-i, --in-interface " "[!] \fIname\fP"
 292 Name of an interface via which a packet was received (only for
 293 packets entering the
 294 .BR INPUT ,
 295 .B FORWARD
 296 and
 297 .B PREROUTING
 298 chains).  When the "!" argument is used before the interface name, the
 299 sense is inverted.  If the interface name ends in a "+", then any
 300 interface which begins with this name will match.  If this option is
 301 omitted, any interface name will match.
 302 .TP
 303 .BR "-o, --out-interface " "[!] \fIname\fP"
 304 Name of an interface via which a packet is going to be sent (for packets
 305 entering the
 306 .BR FORWARD ,
 307 .B OUTPUT
 308 and
 309 .B POSTROUTING
 310 chains).  When the "!" argument is used before the interface name, the
 311 sense is inverted.  If the interface name ends in a "+", then any
 312 interface which begins with this name will match.  If this option is
 313 omitted, any interface name will match.
 314 .TP
 315 .B "[!] " "-f, --fragment"
 316 This means that the rule only refers to second and further fragments
 317 of fragmented packets.  Since there is no way to tell the source or
 318 destination ports of such a packet (or ICMP type), such a packet will
 319 not match any rules which specify them.  When the "!" argument
 320 precedes the "-f" flag, the rule will only match head fragments, or
 321 unfragmented packets.
 322 .TP
 323 .BI "-c, --set-counters " "PKTS BYTES"
 324 This enables the administrator to initialize the packet and byte
 325 counters of a rule (during
 326 .B INSERT,
 327 .B APPEND,
 328 .B REPLACE
 329 operations).
 330 .SS "OTHER OPTIONS"
 331 The following additional options can be specified:
 332 .TP
 333 .B "-v, --verbose"
 334 Verbose output.  This option makes the list command show the interface
 335 name, the rule options (if any), and the TOS masks.  The packet and
 336 byte counters are also listed, with the suffix 'K', 'M' or 'G' for
 337 1000, 1,000,000 and 1,000,000,000 multipliers respectively (but see
 338 the
 339 .B -x
 340 flag to change this).
 341 For appending, insertion, deletion and replacement, this causes
 342 detailed information on the rule or rules to be printed.
 343 .TP
 344 .B "-n, --numeric"
 345 Numeric output.
 346 IP addresses and port numbers will be printed in numeric format.
 347 By default, the program will try to display them as host names,
 348 network names, or services (whenever applicable).
 349 .TP
 350 .B "-x, --exact"
 351 Expand numbers.
 352 Display the exact value of the packet and byte counters,
 353 instead of only the rounded number in K's (multiples of 1000)
 354 M's (multiples of 1000K) or G's (multiples of 1000M).  This option is
 355 only relevant for the
 356 .B -L
 357 command.
 358 .TP
 359 .B "--line-numbers"
 360 When listing rules, add line numbers to the beginning of each rule,
 361 corresponding to that rule's position in the chain.
 362 .TP
 363 .B "--modprobe=command"
 364 When adding or inserting rules into a chain, use
 365 .B command
 366 to load any necessary modules (targets, match extensions, etc).
 367 .SH MATCH EXTENSIONS
 368 iptables can use extended packet matching modules.  These are loaded
 369 in two ways: implicitly, when
 370 .B -p
 371 or
 372 .B --protocol
 373 is specified, or with the
 374 .B -m
 375 or
 376 .B --match
 377 options, followed by the matching module name; after these, various
 378 extra command line options become available, depending on the specific
 379 module.  You can specify multiple extended match modules in one line,
 380 and you can use the
 381 .B -h
 382 or
 383 .B --help
 384 options after the module has been specified to receive help specific
 385 to that module.
 386
 387 The following are included in the base package, and most of these can
 388 be preceded by a
 389 .B !
 390 to invert the sense of the match.
 391 .\" @MATCH@
 392 .SH TARGET EXTENSIONS
 393 iptables can use extended target modules: the following are included
 394 in the standard distribution.
 395 .\" @TARGET@
 396 .SH DIAGNOSTICS
 397 Various error messages are printed to standard error.  The exit code
 398 is 0 for correct functioning.  Errors which appear to be caused by
 399 invalid or abused command line parameters cause an exit code of 2, and
 400 other errors cause an exit code of 1.
 401 .SH BUGS
 402 Bugs?  What's this? ;-)
 403 Well, you might want to have a look at http://bugzilla.netfilter.org/
 404 .SH COMPATIBILITY WITH IPCHAINS
 405 This
 406 .B iptables
 407 is very similar to ipchains by Rusty Russell.  The main difference is
 408 that the chains
 409 .B INPUT
 410 and
 411 .B OUTPUT
 412 are only traversed for packets coming into the local host and
 413 originating from the local host respectively.  Hence every packet only
 414 passes through one of the three chains (except loopback traffic, which
 415 involves both INPUT and OUTPUT chains); previously a forwarded packet
 416 would pass through all three.
 417 .PP
 418 The other main difference is that
 419 .B -i
 420 refers to the input interface;
 421 .B -o
 422 refers to the output interface, and both are available for packets
 423 entering the
 424 .B FORWARD
 425 chain.
 426 .PP The various forms of NAT have been separated out;
 427 .B iptables
 428 is a pure packet filter when using the default `filter' table, with
 429 optional extension modules.  This should simplify much of the previous
 430 confusion over the combination of IP masquerading and packet filtering
 431 seen previously.  So the following options are handled differently:
 432 .nf
 433  -j MASQ
 434  -M -S
 435  -M -L
 436 .fi
 437 There are several other changes in iptables.
 438 .SH SEE ALSO
 439 .BR iptables-save (8),
 440 .BR iptables-restore (8),
 441 .BR ip6tables (8),
 442 .BR ip6tables-save (8),
 443 .BR ip6tables-restore (8).
 444 .P
 445 The packet-filtering-HOWTO details iptables usage for
 446 packet filtering, the NAT-HOWTO details NAT,
 447 the netfilter-extensions-HOWTO details the extensions that are
 448 not in the standard distribution,
 449 and the netfilter-hacking-HOWTO details the netfilter internals.
 450 .br
 451 See
 452 .BR "http://www.netfilter.org/" .
 453 .SH AUTHORS
 454 Rusty Russell wrote iptables, in early consultation with Michael
 455 Neuling.
 456 .PP
 457 Marc Boucher made Rusty abandon ipnatctl by lobbying for a generic packet
 458 selection framework in iptables, then wrote the mangle table, the owner match,
 459 the mark stuff, and ran around doing cool stuff everywhere.
 460 .PP
 461 James Morris wrote the TOS target, and tos match.
 462 .PP
 463 Jozsef Kadlecsik wrote the REJECT target.
 464 .PP
 465 Harald Welte wrote the ULOG target, TTL, DSCP, ECN matches and targets.
 466 .PP
 467 The Netfilter Core Team is: Marc Boucher, Martin Josefsson, Jozsef Kadlecsik,
 468 Patrick McHardy, James Morris, Harald Welte and Rusty Russell.
 469 .PP
 470 Man page written by Herve Eychenne <rv@wallfire.org>.
 471 .\" .. and did I mention that we are incredibly cool people?
 472 .\" .. sexy, too ..
 473 .\" .. witty, charming, powerful ..
 474 .\" .. and most of all, modest ..