17.3. Options Used within iptables Commands
Rules for filtering packets are put in place using the iptables command. When using the iptables command, the following aspects of the packet are most often used as criteria:
Packet Type — Specifies the type of packets the command filters.
Packet Source/Destination — Specifies which packets the command filters based on the source or destination of the packet.
Target — Specifies what action is taken on packets matching the above criteria.
For more information on specific options which address these aspects of a packet, refer to Section 17.3.4 iptables Match Options and Section 17.3.5 Target Options.
The options used with given iptables rule must be grouped logically, based on the purpose and conditions of the overall rule, for the rule to be valid. The remainder of this section explains commonly-used options for the iptables command.
17.3.1. Structure of iptables Options
Many iptables commands have the following structure:
iptables [-t <table-name>] <command> <chain-name> <parameter-1> \
<option-1> <parameter-n> <option-n> |
The <table-name> option allows the user to select a table other than the default filter table to use with the command. The <command> option dictates a specific action to perform, such as appending or deleting the rule specified by the <chain-name> option. Following the <chain-name> are pairs of parameters and options that define what happens when a packet matches the rule.
When looking at the structure of an iptables command, it is important to remember that, unlike most other commands, the length and complexity of an iptables command can change based on its purpose. A command to remove a rule from a chain can be very short, while a command designed to filter packets from a particular subnet using a variety of specific parameters and options can be rather lengthy. When creating iptables commands it is helpful to recognize that some parameters and options may create the need for other parameters and options to further specify the previous option's request. To construct a valid rule, this must continue until every parameter and option that requires another set of options is satisfied.
Type iptables -h to view a comprehensive list of iptables command structures.
17.3.2. Command Options
Command options instruct iptables to perform a specific action. Only one command option is allowed per iptables command. With the exception of the help command, all commands are written in upper-case characters.
The iptables commands are as follows:
-A — Appends the iptables rule to the end of the specified chain. This is the command used to add a rule when rule order in the chain does not matter.
-C — Checks a particular rule before adding it to the user-specified chain. This command can help you construct complicated iptables rules by prompting you for additional parameters and options.
-D — Deletes a rule in a particular chain by number (such as 5 for the fifth rule in a chain). You can also type the entire rule, and iptables deletes the rule in the chain that matches it.
-E — Renames a user-defined chain. This does not affect the structure of the table.
-F — Flushes the selected chain, which effectively deletes every rule in the the chain. If no chain is specified, this command flushes every rule from every chain.
-h — Provides a list of command structures, as well as a quick summary of command parameters and options.
-I — Inserts a rule in a chain at a point specified by a user-defined integer value. If no number is specified, iptables places the command at the top of the chain.
Caution Be aware when using the -A or -I option that the order of the rules within a chain are important for determining which rules apply to which packets.
-L — Lists all of the rules in the chain specified after the command. To list all rules in all chains in the default filter table, do not specify a chain or table. Otherwise, the following syntax should be used to list the rules in a specific chain in a particular table:
iptables -L <chain-name> -t <table-name>
Additional options for the -L command option which provide rule numbers and allow more verbose rule descriptions are described in Section 17.3.6 Listing Options.
-N — Creates a new chain with a user-specified name.
-P — Sets the default policy for the specified chain, so that when packets traverse an entire chain without matching a rule, they are sent on to the specified target, such as ACCEPT or DROP.
-R — Replaces a rule in the specified chain. The rule's number must be specified after the chain's name. The first rule in a chain corresponds to rule number one.
-X — Deletes a user-specified chain. Deleting a built-in chain for any table is not allowed.
-Z — Zeros the byte and packet counters in all chains for a table.
17.3.3. iptables Parameter Options
Once certain iptables commands are specified, including those used to add, append, delete, insert, or replace rules within a particular chain, parameters are required to construct a packet filtering rule.
-c — Resets the counters for a particular rule. This parameter accepts the PKTS and BYTES options to specify what counter to reset.
-d — Sets the destination hostname, IP address, or network of a packet that matches the rule. When matching a network, the following IP address/netmask formats are supported:
N.N.N.N/M.M.M.M — Where N.N.N.N is the IP address range and M.M.M.M is the netmask.
N.N.N.N/M — Where N.N.N.N is the IP address range and M is the bitmask.
-f — Applies this rule only to fragmented packets.
By using the ! option after this parameter, only unfragmented packets are matched.
-i — Sets the incoming network interface, such as eth0 or ppp0. With iptables, this optional parameter may only be used with the INPUT and FORWARD chains when used with the filter table and the PREROUTING chain with the nat and mangle tables.
This parameter also supports the following special options:
! — Reverses the directive, meaning any specified interfaces are excluded from this rule.
+ — A wildcard character used to match all interfaces that match the specified string. For example, the parameter -i eth+ would apply this rule to any Ethernet interfaces but exclude any other interfaces, such as ppp0.
If the -i parameter is used but no interface is specified, then every interface is affected by the rule.
-j — Jumps to the specified target when a packet matches a particular rule. Valid targets to be used after the -j option include the standard options (ACCEPT, DROP, QUEUE, and RETURN) as well as extended options that are available through modules loaded by default with the Red Hat Enterprise Linux iptables RPM package, such as LOG, MARK, and REJECT, among others. Refer to the iptables man page for more information about these and other targets.
It is also possible to direct a packet matching this rule to a user-defined chain outside of the current chain so that other rules can be applied to the packet.
If no target is specified, the packet moves past the rule with no action taken. However, the counter for this rule increases by one.
-o — Sets the outgoing network interface for a rule and may only be used with OUTPUT and FORWARD chains in the filter table, and the POSTROUTING chain in the nat and mangle tables. This parameter's options are the same as those of the incoming network interface parameter (-i).
-p — Sets the IP protocol for the rule, which can be either icmp, tcp, udp, or all, to match every supported protocol. In addition, any protocols listed in /etc/protocols may also be used. If this option is omitted when creating a rule, the all option is the default.
-s — Sets the source for a particular packet using the same syntax as the destination (-d) parameter.
17.3.4. iptables Match Options
Different network protocols provide specialized matching options which can be configured to match a particular packet using that protocol. However, the protocol must first be specified in the iptables command. For example -p tcp <protocol-name> (where <protocol-name> is the target protocol), makes options for the specified protocol available.
17.3.4.1. TCP Protocol
These match options are available for the TCP protocol (-p tcp):
--dport — Sets the destination port for the packet. Use either a network service name (such as www or smtp), port number, or range of port numbers to configure this option. To browse the names and aliases of network services and the port numbers they use, view the /etc/services file. The --destination-port match option is synonymous with --dport.
To specify a specific range of port numbers, separate the two numbers with a colon (:), such as -p tcp --dport 3000:3200. The largest acceptable valid range is 0:65535.
Use an exclamation point character (!) after the --dport option to match all packets which do not use that network service or port.
--sport — Sets the source port of the packet using the same options as --dport. The --source-port match option is synonymous with --sport.
--syn — Applies to all TCP packets designed to initiate communication, commonly called SYN packets. Any packets that carry a data payload are not touched. Placing an exclamation point character (!) as a flag after the --syn option causes all non-SYN packets to be matched.
--tcp-flags — Allows TCP packets with specific bits, or flags, set to be matched with a rule. The --tcp-flags match option accepts two parameters. The first parameter is the mask, which sets the flags to be examined in the packet. The second parameter refers to the flag that must be set to match.
The possible flags are:
ACK
FIN
PSH
RST
SYN
URG
ALL
NONE
For example, an iptables rule which contains -p tcp --tcp-flags ACK,FIN,SYN SYN only matches TCP packets that have the SYN flag set and the ACK and FIN flags unset.
Using the exclamation point character (!) after --tcp-flags reverses the effect of the match option.
--tcp-option — Attempts to match with TCP-specific options that can be set within a particular packet. This match option can also be reversed with the exclamation point character (!).
17.3.4.2. UDP Protocol
These match options are available for the UDP protocol (-p udp):
--dport — Specifies the destination port of the UDP packet, using the service name, port number, or range of port numbers. The --destination-port match option is synonymous with --dport. Refer to the --dport match option in Section 17.3.4.1 TCP Protocol for ways to use this option.
--sport — Specifies the source port of the UDP packet, using the service name, port number, or range of port numbers. The --source-port match option is synonymous with --sport. Refer to the --sport match option in Section 17.3.4.1 TCP Protocol for ways to use this option.
17.3.4.3. ICMP Protocol
The following match options are available for the Internet Control Message Protocol (ICMP) (-p icmp):
--icmp-type — Sets the name or number of the ICMP type to match with the rule. A list of valid ICMP names can be retrieved by typing the iptables -p icmp -h command.
17.3.4.4. Additional Match Option Modules
Additional match options are also available through modules loaded by the iptables command. To use a match option module, load the module by name using the -m option, such as -m <module-name> (replacing <module-name> with the name of the module).
A large number of modules are available by default. It is even possible to create modules that provide additional functionality.
The following is a partial list of the most commonly used modules:
limit module — Places limits on how many packets are matched to a particular rule. This is especially beneficial when used in conjunction with the LOG target as it can prevent a flood of matching packets from filling up the system log with repetitive messages or using up system resources. Refer to Section 17.3.5 Target Options for more information about the LOG target.
The limit module enables the following options:
--limit — Sets the number of matches for a particular range of time, specified with a number and time modifier arranged in a <number>/<time> format. For example, using --limit 5/hour only lets a rule match 5 times in a single hour.
If a number and time modifier are not used, the default value of 3/hour is assumed.
--limit-burst — Sets a limit on the number of packets able to match a rule at one time. This option should be used in conjunction with the --limit option, and it accepts a number to set the burst threshold.
If no number is specified, only five packets are initially able to match the rule.
state module — Enables state matching.
The state module enables the following options:
--state — match a packet with the following connection states:
ESTABLISHED — The matching packet is associated with other packets in an established connection.
INVALID — The matching packet cannot be tied to a known connection.
NEW — The matching packet is either creating a new connection or is part of a two-way connection not previously seen.
RELATED — The matching packet is starting a new connection related in some way to an existing connection.
These connection states can be used in combination with one another by separating them with commas, such as -m state --state INVALID,NEW.
mac module — Enables hardware MAC address matching.
The mac module enables the following option:
--mac-source — Matches a MAC address of the network interface card that sent the packet. To exclude a MAC address from a rule, place an exclamation point (!) after the --mac-source match option.
To view other match options available through modules, refer to the iptables man page.
17.3.5. Target Options
Once a packet has matched a particular rule, the rule can direct the packet to a number of different targets that decide its fate and, possibly, take additional actions. Each chain has a default target, which is used if none of the rules on that chain match a packet or if none of the rules which match the packet specify a target.
The following are the standard targets:
<user-defined-chain> — Replace <user-defined-chain> with the name of a user-defined chain within the table. This target passes the packet to the target chain.
ACCEPT — Allows the packet to successfully move on to its destination or another chain.
DROP — Drops the packet without responding to the requester. The system that sent the packet is not notified of the failure.
QUEUE — The packet is queued for handling by a user-space application.
RETURN — Stops checking the packet against rules in the current chain. If the packet with a RETURN target matches a rule in a chain called from another chain, the packet is returned to the first chain to resume rule checking where it left off. If the RETURN rule is used on a built-in chain and the packet cannot move up to its previous chain, the default target for the current chain decides what action to take.
In addition to these standard targets, various other targets may be used with extensions called target modules. For more information about match option modules, refer to Section 17.3.4.4 Additional Match Option Modules.
There are many extended target modules, most of which only apply to specific tables or situations. A couple of the most popular target modules included by default in Red Hat Enterprise Linux are:
LOG — Logs all packets that match this rule. Since the packets are logged by the kernel, the /etc/syslog.conf file determines where these log entries are written. By default, they are placed in the /var/log/messages file.
Additional options can be used after the LOG target to specify the way in which logging occurs:
--log-level — Sets the priority level of a logging event. A list of priority levels can be found within the syslog.conf man page.
--log-ip-options — Any options set in the header of a IP packet is logged.
--log-prefix — Places a string of up to 29 characters before the log line when it is written. This is useful for writing syslog filters for use in conjunction with packet logging.
--log-tcp-options — Any options set in the header of a TCP packet are logged.
--log-tcp-sequence — Writes the TCP sequence number for the packet in the log.
REJECT — Sends an error packet back to the remote system and drops the packet.
The REJECT target accepts --reject-with <type> (where <type> is the rejection type) allowing more detailed information to be sent back with the error packet. The message port-unreachable is the default <type> error given if no other option is used. For a full list of <type> options, refer to the iptables man page.
Other target extensions, including several that are useful for IP masquerading using the nat table or with packet alteration using the mangle table, can be found in the iptables man page.
17.3.6. Listing Options
The default list command, iptables -L, provides a very basic overview of the default filter table's current chains. Additional options provide more information:
-v — Displays verbose output, such as the number of packets and bytes each chain has seen, the number of packets and bytes each rule has matched, and which interfaces apply to a particular rule.
-x — Expands numbers into their exact values. On a busy system, the number of packets and bytes seen by a particular chain or rule may be abbreviated using K (thousands), M (millions), and G (billions) at the end of the number. This option forces the full number to be displayed.
-n — Displays IP addresses and port numbers in numeric format, rather than the default hostname and network service format.
--line-numbers — Lists rules in each chain next to their numeric order in the chain. This option is useful when attempting to delete the specific rule in a chain or to locate where to insert a rule within a chain.
-t — Specifies a table name.