Table of Contents

Primary Commands
Primary commands form groups of rules within a FireHOL firewall. The optional rule parameters given to the primary commands are indirectly applied to all sub-commands given within this primary command.

interface <real interface> <name> [optional rule parameters]

Description

The interface command creates a firewall for protecting the host the firewall is running, from the given interface.
The default interface policy is drop, so that if no subcommands are given, the firewall will just drop all incoming and outgoing traffic using this interface.

INPORTANT
Note that unlike ipchains, in iptables traffic passing through the firewall host (FORWARDed traffic) does not pass through the INPUT/OUTPUT chains of the firewall and therefore the interface rules in FireHOL never match it. To match the traffic passing through (even if DNATed) you have to place the filtering rules in router statements. Interface statements filter traffic only from/to the firewall host. Nothing else.

Parameters


router <name> [optional rule parameters]

Description

The router command creates a firewall for the traffic passing through the host running the firewall. The default policy on router commands is return. This means that by default no packets are dropped in a router. Packets not matched by any router command will be dropped at the end of the firewall. Change the default policy of a router only if you understand clearly what gets matched by the router statement. It is very common to have overlapping definitions of routers and changing this policy to anything other than the default may have strange results for your configuration. (Changing the policy on routers appeared in v1.248).

INPORTANT
Note that unlike ipchains, in iptables traffic passing through the firewall host (FORWARDed traffic) does not pass through the INPUT/OUTPUT chains of the firewall and therefore the interface rules in FireHOL never match it. To match the traffic passing through (even if DNATed) you have to place the filtering rules in router statements. Interface statements filter traffic only from/to the firewall host. Router statements filter traffic that passes through the firewall host.

Parameters

Router statements produce similar iptables commands the interface statements produce. For each router statement an in_<name> and an out_<name> chain are produced to match the traffic in both directions of the router.
To match some client or server traffic the administrator has to specify the input/output interface or the source/destination of the request. All inface/outface, src/dst optional rule parameters can be given either on the router statement in which case will be applied to all subcommands for this router, or on each subcommand within a router. Both are valid.
For example:
		router mylan inface ppp+ outface eth0
			server http accept
			client smtp accept
	
The above says: Define a router that matches all requests that originate from some PPP interface and go out to eth0.
There is an HTTP server in eth0 that client from the PPP interfaces are allowed to reach.
Clients on eth0 are allowed to get SMTP traffic from the PPP interfaces.

While:
		router mylan
			server http accept inface ppp+ outface eth0
			server smtp accept inface eth0 outface ppp+
	
The above says: Define a router that matches any kind of forwarded traffic.
For HTTP traffic the clients are on a PPP interface and the servers on eth0.
For SMTP traffic the clients are on a eth0 interface and the servers o a PPP interface.

Please note that in the second example the SMTP traffic is matched again with a server subcommand, not a client (as in the first example).

The client subcommand reverses all the optional rules that are applied indirectly to it. Indirect rule parameters are those that are inherited from the parent command (router in this case).
To make it simple, for FireHOL a client is: "a server with all the implicit optional rule parameters reversed".

So, in the first example, the client simply flipped the inface and outface rules defined at the router and became an SMTP server.
In the second example there is nothing to be flipped, so server and client are exactly the same.

I suggest to use client subcommands in routers only if you have inface/outface or src/dst in the router statements. If you are building routers like the second example, don't use client, it is confusing.

Older versions of FireHOL did not allow server and client subcommands in routers. Only the route subcommand was allowed. Today, route is just an alias for server and can be used only in routers, not interfaces.

Any number of router statements can exist. Since the policy is RETURN on all of them, any traffic not matched by a router will continue to be checked against the second.

Sub-Commands
Subcommands must be given within Primary commands.

policy <action>

Description

The policy subcommand defines the default policy for an interface.

This directive accepts all the actions specified in Actions.

Please note that FireHOL is only useful for "DROP/REJECT EVERYTHING, ALLOW EXPLICITLY" type of firewalls. By changing the policy to accept, you CANNOT create valid "ACCEPT EVERYTHING, DROP EXPLICITLY" firewalls.
The policy should be set to accept only if you really trust the hosts that can reach the machine via this interface. For information about this, see: Bug 927532.


protection [reverse] <type> [requests/sec [burst]]

Description

The protection subcommand sets a number of protection rules on an interface.

In router configurations, protections are setup on inface. The reverse keyword will make the protections setup on outface. Please note that the reverse keyword must be the first given. Otherwise it will not work.

type can be:


server <service> <action> [optional rule parameters]

Description

The server subcommand defines a server of a service. For FireHOL a server is the destination of a request, and even if this is more complex for multi-socket services, for FireHOL a server always accepts requests.

The optional rule parameters given to the parent primary command (interface or router) are inherited by the server as they have been given.


This subcommand can be used on both interfaces and routers.

Parameters


client <service> <action> [optional rule parameters]

The client subcommand defines a client of a service. For FireHOL a client is the source of a request. FireHOL follows this simple rule even on multi-socket complex protocols, so that for FireHOL a client always sends requests.
The parameters are exactly the same with the server subcommand.

The optional rule parameters given to the parent primary command (interface or router) are inherited by the client, but they are reversed. For an explanation of this please refer to the documentation of the router primary command.


This subcommand can be used on both interfaces and routers.


route <service> <action> [optional rule parameters]

The route subcommand is an alias for the server command that can be used only on routers, not interfaces.


group with [optional rule parameters]

group end

The group subcommand allows grouping for server and client subcommands that share common optional rule parameters.

There is only one reason for using groups: Optimization of the generated firewall rules. With groups, all the optional rule parameters are checked only once, while entering the group, and then each service is applied without extra processing.

For example:


	interface any world
		server http accept
		
		# trusted services
		group with src "1.2.3.4 5.6.7.8"
			server ssh	accept
			server telnet	accept
		group end
		
		client all accept
The above will be optimal compared with server "ssh telnet" accept src "1.2.3.4 5.6.7.8".

FireHOL supports nested groups.

Helper Commands
Helper commands provide shortcuts for common functions not handled by the core of FireHOL's logic.

action [chain <name> <action>

The action helper creates an iptables chain which can be used to control the action of other firewall rules during runtime. For example, you can setup the custom action ACT1, which by default is ACCEPT, but under certain cases it can be changed to DROP, REJECT or RETURN without restarting the firewall.

The first argument must always be the word chain, for the moment.

Example 1:

At the top of firehol.conf, create the action ACT1:

action chain ACT1 accept

later, in interfaces and routers, create rules that use the ACT1 action:

server smtp ACT1 client imap ACT1

Please note that actions created this way are case sensitive.
At some point, and while the firewall is running, the action ACT1 can be changed to DROP, with this linux command (this is not FireHOL specific):

iptables -t filter -I ACT1 -j DROP

The above command inserts (-I) the new action DROP above the default action ACCEPT, and therefore all the traffic matching the FireHOL rules that have the action ACT1 will now be dropped.
To return to the default action (ACCEPT), run the following linux command:

iptables -t filter -D ACT1 -j DROP

This command deletes (-D) the DROP action that was inserted above the default action. If you delete all actions in the chain ACT1, the default action will be RETURN, in which case all rules with action ACT1 will be neutralized (it will be the same as they were not specified at all in firehol.conf).

Example 2: action chain "ACT1 ACT2 ACT3" accept chain "ACT4 ACT5 ACT6" drop # will create 6 actions, ACT1, ACT2, ACT3 with ACCEPT and ACT4, ACT5, ACT6 with DROP


blacklist [option] <IPs>

The blacklist helper creates a blacklist for the IP addresses given. It supports two modes of operation based on the option given (or the absence of it).

The option can be:

The blacklist helper affects both interfaces and routers and can be used as many times as needed, but before the first interface statement. The blacklist helper accepts multiple IPs both as one quoted and space separated list and as separate arguments.

Example 1: blacklist this "195.97.5.202 10.1.1.1" # please note the quotes
Example 2: blacklist full 195.97.5.202 10.1.1.1 # please note the absence of quotes


classify <CLASS> [optional rule parameters]

The classify helper classifies the traffic into a specific traffic shapping class.

Parameters


Example 1: classify 1:1 outface eth1 proto tcp dport 25, will send all smtp traffic going out via eth1 to class 1:1.


connmark <VALUE> <WHERE> [optional rule parameters]

The connmark helper is used to set a mark on a whole connection in both directions of the traffic automatically. The difference with mark is that the later just marks the packets matched by the optional rule parameters, while connmark marks the whole statefull connection.

Parameters

Example 1: Let's say that you have 3 ethernet interfaces: eth0, eth1 and eth2. eth0 connects you to the LAN, while eth1 and eth2 connect you to the internet via 2 different service providers. You want to guarrantee that when a connection is coming from provider 1 (eth1) will go back through this provider and the same for provider 2 (eth2).

Step 1: You mark the connections when they enter the firewall host from the provider interfaces:
connmark 1 PREROUTING inface eth1
connmark 2 PREROUTING inface eth2

Step 2: You restore the mark (from the connmark) when the packets come in from the LAN:
connmark restore OUTPUT
connmark restore PREROUTING inface eth0

Now you can use iproute2 to pick the right routing table (eth1 or eth2 and the default gateway) based on the MARK of the packets.

Example 2: connmark 1 PREROUTING inface eth1, Set the CONNMARK 1 to all packets coming in from eth1.
Example 3: connmark save PREROUTING inface eth1, Save the MARK value to the CONNMARK value on all packets coming in from eth1.


dnat [to] <target> [optional rule parameters]

The dnat helper sets up a Destination NAT rule for routed traffic, by calling
nat to-destination <target> [optional rule parameters]

See the nat helper.

Example: dnat to 1.1.1.1 inface eth0 src 2.2.2.2 dst 3.3.3.3


dscp <NUMBER> <WHERE> [optional rule parameters]


dscp class <CLASSID> <WHERE> [optional rule parameters]

The dscp helper sets the DSCP field in the header of the packets matching the optional rule parameters.

Parameters


Example 1: dscp 32 OUTPUT, will set the DSCP field to 32 of all packets sent by the local machine.
Example 2: dscp 0x20 FORWARD, will set DCSP to 0x20 (32) of all packets passing through the local machine.
Example 3: dscp class EF FORWARD proto tcp dport 25 dst 1.1.1.1 src 2.2.2.2, will set DSCP to DeffServ class EF for all packets sent by 2.2.2.2, passing through the local machine and targeting port TCP/25 of host 1.1.1.1.


ecn_shame

The ecn_shame helper checks if Explicit Congestion Notification (ECN) is enabled in the kernel, and if it is, it fetches the ECN Hall of Shame list and disables ECN for all hosts present in the list.


iptables <arguments>

Description

The iptables command passes all its arguments to the real iptables command, during run-time.

You should not use in FireHOL configurations /sbin/iptables or other means to alter a FireHOL firewall. If you do, your commands will be run before FireHOL activates its firewall and while the previous firewall is still running. Also, since FireHOL will delete all previous firewall rules in order to activate the new firewall, any changes you will make, will be deleted too.

Always use the iptables directive to hook iptables commands in a FireHOL firewall. Nothing else.


mac <IP> <MAC>

The mac helper verifies that all traffic comming in with source the IP address, comes from the MAC address. The helper applies its rules to filter/INPUT and filter/FORWARD and checks the source IP address in combination with the source MAC address.

The same MAC address is allowed to use other IPs; only the specific IP is required to be used with the specified MAC address.

Packets with the given IP address but with wrong MAC address will be DROPped and a log (as in loglimit) with label "MAC MISSMATCH" will appear in the system logs.

This helper has to be used before all interface or router statements. Of course, you can use as many mac statements as you wish.

Example: mac 195.97.5.202 00:02:8a:21:a9:d8


mark <NUMBER> <WHERE> [optional rule parameters]

The mark helper marks the traffic with a specific mark NUMBER that can be matched by traffic shapping tools for controlling the traffic.

Parameters

Keep in mind that if you need to do policy based routing based on iptables marks, you should disable the Root Path Filtering on the interfaces involved (rp_filter in sysctl).
Example 1: mark 1 OUTPUT, will mark with 1 all packets send by the local machine.
Example 2: mark 2 FORWARD, will mark with 2 all packets passing through the local machine.
Example 3: mark 3 FORWARD proto tcp dport 25 dst 1.1.1.1 src 2.2.2.2, will match with 3 all packets sent by 2.2.2.2, passing through the local machine and targeting port TCP/25 of host 1.1.1.1.


masquerade [reverse | interface] [optional rule parameters]

Masquerading is a special from of SNAT (Source NAT) that changes the source of requests when they go out and replaces their original source when replies come in. This way a Linux box can become an internet router for a LAN of clients having unroutable IP addresses. Masquerading takes care to re-map IP addresses and ports as required.

Masquerading is "expensive" compared to SNAT because it checks the IP address of the ougoing interface every time for every packet, and therefore it is suggested that if you connect to the internet with a static IP address, to prefer SNAT.

The masquerade helper sets up masquerading on the output of a network interface (not the interface command, but a real network interface).

If the masquerade command is placed within an interface command, its network interface(s) will be used.
If the masquerade command is placed within a router command that has an outface defined, then the outface network interface(s) will be used.
If placed within a router command but the keyword reverse is specified and the router command has an inface defined, then the inface network interface(s) will be used.
If placed outside and before all primary commands, an interface (or list of space separated interfaces, within double quotes) can be specified on the masquerade command.

In all cases, masquerade will setup itself on the output of the given interface(s).

Please note that if masquerade is used within some interface or router, it does not respect the optional rule parameters given to this interface or router command. Masquerade uses only its own optional rule parameters.

inface and outface should not be given as parameters to masquerade (inface because iptables does not support this in the POSTROUTING chain, and outface because it will be overwritten by the interface(s) mentioned above).

Finally, the masquerade helper will turn on FIREHOL_NAT and instruct the kernel to do packet forwarding (like the router commands do).

Example 1: before the first interface or router: masquerade eth0 src 10.0.0.0/8 dst not 10.0.0.0/8
Example 2: within an interface: masquerade, to masquerade on the output of this interface
Example 3: within a router: masquerade reverse, to masquerade on the output of the router's inface.


nat <type> <target> [optional rule parameters]

The nat helper sets up a NAT rule for routed traffic.

The type parameter can be:

Please understand that the optional rule parameters are used only to limit the traffic to be matched. Consider these examples:

CommandDescription
nat to-destination 1.1.1.1 Sends to 1.1.1.1 all traffic comming in or passing trhough the firewall host.
nat to-destination 1.1.1.1 dst 2.2.2.2 Redirects to 1.1.1.1 all traffic comming in or passing through, and going to 2.2.2.2.
nat to-destination 1.1.1.1 proto tcp dst 2.2.2.2 Redirects to 1.1.1.1 all TCP traffic comming in or passing through and going to 2.2.2.2.
nat to-destination 1.1.1.1 proto tcp dport 25 dst 2.2.2.2 Redirects to 1.1.1.1 all traffic comming in or passing through and going to 2.2.2.2 to port tcp/25.
nat to-destination 1.1.1.1 proto tcp dport 25 dst 2.2.2.2 src 3.3.3.3 Redirects to 1.1.1.1 all traffic comming in or passing through from 3.3.3.3 and going to 2.2.2.2 to port tcp/25.

Example 1: nat to-source 1.1.1.1 outface eth0 src 2.2.2.2 dst 3.3.3.3
Example 2: nat to-destination 4.4.4.4 inface eth0 src 5.5.5.5 dst 6.6.6.6
Example 3: nat redirect-to 8080 inface eth0 src 2.2.2.0/24 proto tcp dport 80


redirect [to] <target> [optional rule parameters]

The redirect helper catches all incomming traffic matching the optional rule parameters given and redirects it to ports on the local host, by calling
nat redirect-to <target> [optional rule parameters]

See the nat helper.

Example: redirect to 8080 inface eth0 src 2.2.2.0/24 proto tcp dport 80


snat [to] <target> [optional rule parameters]

The snat helper sets up a Source NAT rule for routed traffic, by calling
nat to-source <target> [optional rule parameters]

See the nat helper.

Example: snat to 1.1.1.1 outface eth0 src 2.2.2.2 dst 3.3.3.3


tcpmss <what>

The tcpmss helper sets the MSS (Maximum Segment Size) of TCP SYN packets routed through the firewall. Its purpose is to overcome situations where Path MTU Discovery is not working and packet fragmentation is not possible.

Within FireHOL, it can be defined either before any primary command, in which case it is applied to all traffic passing through the firewall, or to any router, in which case it is applied to traffic going out on the outfaces of the router.

The argument can either be the word auto or a number:

See also TCPMSS target in iptables tutorial.

Example 1: tcpmss auto
Example 2: tcpmss 500


tos <NUMBER> <WHERE> [optional rule parameters]

The tos helper sets the Type of Service (TOS) in packets.

Parameters


Example 1: tos 16 OUTPUT, will set TOS to 16 for all packets sent by the local machine.
Example 2: tos 0x10 FORWARD, will set TOS to 0x10 (16) for all packets passing through the local machine.
Example 3: tos Maximize-Throughput FORWARD proto tcp dport 25 dst 1.1.1.1 src 2.2.2.2, will set TOS to Maximize-Throughput (8) for all packets sent by 2.2.2.2, passing through the local machine and targeting port TCP/25 of host 1.1.1.1.


tosfix

The tosfix helper is based on the suggestions given by Erik Hensema for iptables and tc shapping tricks (check the source here). It does:


transparent_proxy <service> <port> <user> [optional rule parameters]

The transparent_proxy helper sets up trasparent proxy server for TCP traffic. The proxy is assumed to be running on the firewall host at port port, with the credentials of the local user user serving TCP port's service requests.

The transparent_proxy helper can be used for two kinds of traffic:

Of course, make sure that your firewall allows requests to reach your proxy server.

In kernel versions prior to 2.6 you need to enable CONFIG_IP_NF_NAT_LOCAL for locally generated outgoing traffic to be redirected correctly.

Example 1: transparent_proxy 80 3128 squid inface eth0 src 10.0.0.0/8 to redirect all tcp/80 requests coming in from eth0 (10.0.0.0/8) to your local web caching proxy server listening at port 3128 and running as user squid.
Example 2: transparent_proxy "80 3128 8080" 8080 "squid privoxy root bin" inface not "ppp+ ipsec+" dst not "a.not.proxied.server" to redirect all web and proxy requests (tcp: 80, 3128, 8080) coming in from all interfaces except ppp+ and ipsec+ to your local squid server listening at tcp/8080 except those requests generated by the local users squid, privoxy, root and bin, and all matching traffic that is targeting host 'a.not.proxied.server'.


transparent_squid <port> <user> [optional rule parameters]

The transparent_squid helper sets up trasparent caching for HTTP traffic. It is equivalent to:

transparent_proxy 80 <port> <user> [optional rule parameters]

Example 1: transparent_squid 3128 squid inface eth0 src 10.0.0.0/8
Example 2: transparent_squid 8080 "squid privoxy root bin" inface not "ppp+ ipsec+" dst not "a.not.proxied.server"


version <number>

Description

The version command states the FireHOL release the configuration file was created for. In case the configuration file is newer than FireHOL, FireHOL will deny to run it.

This command is here to allow you or anyone else design and distribute FireHOL configuration files, while ensuring that the correct FireHOL version is going to run them.

Since FireHOL configurations are BASH script, it is relatively easy to use FireHOL configurations as small scripts that dynamically process rules stored in a database, in a file system as separate files, or elsewhere. This directive will help the developers of FireHOL configurations to control the required version of FireHOL.

The FireHOL release is increased every time the format of the configuration file and the internals of FireHOL are changed.

Since FireHOL v1.67 version is not required to be present in every configuration file.

Actions
Actions are the actions to be taken on services and traffic described by other commands and functions. Please note that normally, FireHOL will pass-through to the generated iptables statements all the possible actions iptables accepts, but only the ones defined here can be used with lower case letters and currently it will be impossible to pass arguments to some unknown action. Also, keep in mind that the iptables action LOG is a FireHOL optional rule parameter (see log and loglimit) that can be defined together with one of the following actions and FireHOL will actually produce multiple iptables statements to achieve both the logging and the action.

accept [with limit <frequency> <burst> [overflow <action>]]

accept [with knock <name>]

accept [with recent <name> <seconds> <hits>]

accept allows the traffic matching the rules to reach its destination.

with limit
The optional parameter with limit offers control over the allowed frequency of NEW connections. frequency and burst have the same syntax of the limit optional rule parameter.

The overflow action offers control over the overflowed NEW connections. The default is to REJECT overflowed connections (not DROP them, since DROP produces timeouts on the otherwise valid service clients). Also, the REJECT overflow action, will reject TCP connections with tcp-reset and all others with icmp-host-unreachable.
The overflowed NEW connection attempts will be logged with a OVERFLOW message, with the options the loglimit parameter works.

with knock
The optional parameter with knock allows easy integration with knockd, a server that allows you to control access to services, by sending certain packets to "knock" the door, before the door is open for service.
This parameter accepts just a name. This name is used to build a special chain knock_<name> which will contain just the rules to allow established connections to work, but it prevent any new connections from taking place. In case, knockd has not allowed new connections, this traffic entering this chain will just return back and continue to match against the other rules until the end of the firewall.

How to use it: lets say that you want to allow https traffic based on a knock. In FireHOL you write:

server https accept with knock hidden

and you configure knockd so that it runs:

iptables -A knock_hidden -s %IP% -j ACCEPT

to enable the https service (notice that there is no need to match anything else than the IP. FireHOL already matches everything needed for its rules to work), and:

iptables -D knock_hidden -s %IP% -j ACCEPT

to disable this service for the given IP.

You can use the same knock name in more than one FireHOL services to enable/disable all the services together, without any extra effort in knockd configuration (just one ACCEPT row like above - i.e. the same knock as far as knockd is concerned - will allow all the FireHOL services with the same knock name to serve requests for the given IP). Check also this forum post.

with recent
The optional parameter with recent allows new connections to be limited per remote IP for a number of seconds and/or hits. The name parameter allows multiple statements to share the same recent list of IPs. If the time or the hits are not required, set them to empty. Keep in mind that when a new connection is not allowed, the traffic will continue to be matched by the rest of the firewall. In other words, if the traffic is not allowed due to the limitations set here, it is not dropped. It is just not matched by this rule.

Example 1: server smtp accept, to allow SMTP requests and their replies to flow.
Example 2: server smtp accept with limit 10/s 100, to allow SMTP requests to come at 10/second max, with a burst of 100, and their replies to flow back.
Example 3: server smtp accept with limit 10/s 100 overflow drop, to allow SMTP requests to come at 10/second max, with a burst of 100, and their replies to flow back. The overflow requests will be dropped.
Example 4: server smtp accept with limit 10/s 100 src "1.2.3.4 5.6.7.8", same as example 2, but the only valid clients are given as argument to src Example 4: server smtp accept with recent mail 60 2, to allow only 2 connections every 60 seconds per remote IP, to the smtp server.


reject [with <message>]

reject discards the matching traffic but sends a rejecting message back to the sender.

with is used to offer control on the message to be returned to the sender. with accepts all the arguments the --reject-with iptables expression accepts. For an updated list of these messages type iptables -j REJECT --help. Bellow you can find the list my system accepts.

By default (no with argument given), reject will send an icmp-port-unreachable on all protocols except TCP, for which it will send a tcp-reset.

MessageAliasDescriptionReference
icmp-net-unreachable net-unreach ICMP network unreachable

From RFC 1812 section 5.2.7.1
Generated by a router if a forwarding path (route) to the destination network is not available.

Notes
Use this with care. The sender and the routers between you and the sender may conclude that the whole network your host resides in, is unreachable and prevent other traffic from reaching you.

RFC 1812 RFC 792
icmp-host-unreachable host-unreach ICMP host unreachable

From RFC 1812 section 5.2.7.1
Generated by a router if a forwarding path (route) to the destination host on a directly connected network is not available (does not respond to ARP).

Notes
Use this with care. The sender and the routers between you and the sender may conclude that your server is unreachable and prevent the transmission of other traffic to you.

RFC 1812 RFC 792
icmp-proto-unreachable proto-unreach ICMP protocol unreachable

From RFC 1812 section 5.2.7.1
Generated if the transport protocol designated in a datagram is not supported in the transport layer of the final destination.

RFC 1812 RFC 792
icmp-port-unreachable port-unreach ICMP port unreachable (default)

From RFC 1812 section 5.2.7.1
Generated if the designated transport protocol (e.g. TCP, UDP, etc) is unable to demultiplex the datagram in the transport layer of the final destination but has no protocol mechanism to inform the sender.

In other words
Generated by hosts to indicate that the required port is not active.

RFC 1812 RFC 792
icmp-net-prohibited net-prohib ICMP communication with destination network administratively prohibited

From RFC 1812 section 5.2.7.1
This code was intended for use by end-to-end encryption devices used by U.S military agencies. Routers SHOULD use the newly defined Code 13 (Communication Administratively Prohibited) if they administratively filter packets.

In other words
Use it, but don't expect that this will be widely understood.

RFC 1812 RFC 1122
icmp-host-prohibited host-prohib ICMP communication with destination host administratively prohibited

From RFC 1812 section 5.2.7.1
This code was intended for use by end-to-end encryption devices used by U.S military agencies. Routers SHOULD use the newly defined Code 13 (Communication Administratively Prohibited) if they administratively filter packets.

In other words
Use it, but don't expect that this will be widely understood.

RFC 1812 RFC 1122
tcp-reset tcp-reset TCP RST

This is the port unreachable message of the TCP stack. It is useful when you want to prevent timeouts on rejected TCP services when the client is badly written to ignore ICMP port unreachable messages.

I suggest to use this for rejecting idents:
server ident reject with tcp-reset.

RFC 1122


Example 1: policy reject with host-unreach
Example 2: server ident reject with tcp-reset
Example 3: UNMATCHED_INPUT_POLICY="reject with host-prohib"


drop

drop silently discards the matching traffic. The fact that the traffic is silently discarded makes the sender timeout in order to conclude that it is not possible to use the wanted service.

Example: server smtp drop, to silently discard SMTP requests and their replies.


deny

deny is just an alias for drop, made for those who are used to ipchains terminology.

Example: server smtp deny, to silently discard SMTP requests and their replies.


tarpit

Captures and holds incoming TCP connections using no local per-connection resources. Connections are accepted, but immediately switched to the persist state (0 byte window), in which the remote side stops sending data and asks to continue every 60-240 seconds. Attempts to close the connection are ignored, forcing the remote side to time out the connection in 12-24 minutes.

Example: server smtp tarpit, to force remote clients to timeout.


return

return will return the flow of processing to the parent of the current command. Currently, it has meaning to specify the action return only as a policy to some interface.

Example: policy return, to have traffic not matched by any rule within an interface to continue traveling through the firewall and possibly matched by other interfaces bellow.


mirror

mirror will return the traffic to the wanted port, back to the sending host. Use this with care, and only if you understand what you doing. Keep also in mind that FireHOL will apply this action to both requests and replies comming in or passing through, and will replace it with REJECT for traffic generated by the local host.


redirect [to-port port]

redirect is used internally by FireHOL Helper Commands to redirect traffic to ports on the local host. Unless you are a developer, you will never need to use this directly.

Optional Rule Parameters
Optional rule parameters are accepted by many commands to narrow the match they do by default. The parameters described bellow are all that FireHOL supports. You should check the documentation of each command to find which parameters should not be used with it. Normally, all FireHOL commands are designed so that if you specify a parameters that is also used internally, the internal one will overwrite the one given in the configuration file. In such a case, FireHOL will present you a warning with the old and the new value.

Not all parameters should be used in all cases. For example sport and dport should not be used in normal server and client commands since such ports are internally defined by the services themselves. In any case, FireHOL will complain about optional rule parameters that should not be used in certain commands.

src [not] <host>

Description

src defines the source IP address of the REQUEST. If src is defined on a server statement it matches the source of the request which is the remote host, while if it is defined on a client statement it matches again the source of the request, but this time it is the local host. Focus on the REQUEST!!! Forget the reply.

Parameters


dst [not] <host>

Description

dst defines the destination of the REQUEST. If dst is defined on a server statement it matches the destination of the request which is the local host, while if it is defined on a client statement it matches again the destination of the request, but this time it is the remote host. Focus on the REQUEST!!! Forget the reply.

dst accepts the same parameters as src


srctype [not] <type>

Description

srctype defines the source IP address type. The following types are supported:

More that one types can be specified if given as a space separated list enclosed in quotes.
FireHOL will convert to upper case any strings given as types.

For more information check: iptables -m addrtype --help (or man iptables).


dsttype [not] <type>

Description

dsttype defines the destination IP address type. This parameter has the same rules with srctype.


inface [not] <interface>

Description

inface defines the interface the REQUEST is received via. inface cannot be used in interface commands.

Parameters


outface [not] <interface>

Description

outface defines the interface the REQUEST is send via. outface cannot be used in interface commands.

outface accepts the same parameters as inface.


physin [not] <interface>

Description

physin defines the physical interface the REQUEST is received via and is used in cases where inface is defined as a virtual interface (such as a bridge interface). In such cases, the physdev iptables module (which is used by physin) can be used to match the physical network interface the REQUEST is recieved via.

physin accepts the same parameters as inface.


physout [not] <interface>

Description

physout defines the physical interface the REQUEST is send via and is used in cases where outface is defined as a virtual interface (such as a bridge interface). In such cases, the physdev iptables module (which is used by physout) can be used to match the physical network interface the REQUEST is send via.

physout accepts the same parameters as outface.


custom "parameters"

Description

custom passes its arguments to the generated iptables commands.

It is required to quote all the parameters given to custom. If the parameters include a space character between some text that is required to be given to iptables as one argument, it is required to escape another set of quotes in order. Another way is to use double quotes externally and single quotes internally.

Example 1: server smtp accept custom "--some-iptables-option and_its_value"
Example 2: server smtp accept custom "--some-iptables-option 'one_value another_value'"


log "<some text>" [level a_level]

Description

log will log the matching packets to syslog. Note that this is not an action (in iptables it is). FireHOL will actually produce multiple iptables commands to accomplish both the action for the rule and the logging. You can control how logging works, by altering the variables FIREHOL_LOG_MODE, FIREHOL_LOG_OPTIONS and FIREHOL_LOG_LEVEL. You can also change the level of just one rule by using the level argument of the log parameter (only when FIREHOL_LOG_MODE=LOG).

FireHOL logs traffic, exactly the same way iptables does. Many users have complained about packet logs appearing at their console. To avoid this you will have to:

Actually klogd's -c option and iptables' --log-level option are the same thing (iptables accepts also the numeric values klogd accepts). If iptables logs at a higher priority than klogd is configured to use, then your packets will appear in the console too.

In most kernels klogd is by default configured to log everything, so if you don't also change klogd's -c option, the --log-level setting of iptables has no effect. Use the table bellow to match klogd options with --log-level options:

PriorityklogdiptablesDescription
0 0 emerg system is unusable
1 1 alert action must be taken immediately
2 2 crit critical conditions
3 3 error error conditions
4 4 warning (default) warning conditions
5 5 notice normal but significant condition
6 6 info informational
7 7 (default) debug debug-level messages

To prevent packet logs appearing to the console, klogd option must be LOWER than the one iptables uses.

On RedHat systems, you can configure klogd by changing /etc/sysconfig/syslog and adding to KLOGD_OPTIONS the required -c level.


loglimit "<some text>"

Description

loglimit is the same with log but limits the frequency of logging according to the setting of FIREHOL_LOG_FREQUENCY and FIREHOL_LOG_BURST.


proto [not] <protocol>

Description

proto sets the required protocol for the traffic. This command accepts anything iptables accepts as protocols.


limit <frequency> <burst>

Description

limit will limit the match in both directions of the traffic (request and reply). This is used internally by FireHOL and its effects has not been tested in the high level configuration file directives.


sport <port>

Description

sport defines the source port of a request. It accepts port names, port numbers, port ranges (FROM:TO) and multiple ports (or ranges) seperated by spaces and quoted as a single argument. This parameter should not be used in normal services definitions (client and server commands) or interface and router definitions, unless you really understand what you are doing.


dport <port>

Description

dport defines the destination port of a request. It accepts port names, port numbers, port ranges (FROM:TO) and multiple ports (or ranges) seperated by spaces and quoted as a single argument. This parameter should not be used in normal services definitions (client and server commands) or interface and router definitions, unless you really understand what you are doing.


uid [not] <user>

user [not] <user>

Description

uid or user define the operating system user sending this traffic. The parameter can be a username, a user number or a list of these two, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands) defined within interfaces, not routers. FireHOL is "smart" enough to apply this parameter only to traffic send by the localhost, i.e. the replies of servers and requests of clients. It is not possible, and FireHOL will simply ignore this parameter, on traffic coming in or passign through the firewall host.


Example 1: client "pop3 imap" accept user not "user1 user2 user3" dst mymailer.example.com
The above will allow local users except user1, user2 and user3 to use POP3 and IMAP services on mymailer.example.com. You can use this, for example, to allow only a few of the local users use the fetchmail program to fetch their mail from the mail server.


Example 2: server http accept user apache
The above will allow all HTTP to reach the local http server, but only if the web server is running as user apache the replies will be send back to the HTTP client.


gid <group>

group <group>

Description

gid or group define the operating system user group sending this traffic. The parameter can be a group name, a group number or a list of these two, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands) defined within interfaces, not routers. FireHOL is "smart" enough to apply this parameter only to traffic send by the localhost, i.e. the replies of servers and requests of clients. It is not possible, and FireHOL will simply ignore this parameter, on traffic coming in or passign through the firewall host.


pid <process>

process <process>

Description

pid or process define the operating system process ID (or PID) sending this traffic. The parameter can be a PID or a list of PIDs, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands) defined within interfaces, not routers. FireHOL is "smart" enough to apply this parameter only to traffic send by the localhost, i.e. the replies of servers and requests of clients. It is not possible, and FireHOL will simply ignore this parameter, on traffic coming in or passign through the firewall host.


sid <session>

session <session>

Description

sid or session define the operating system session ID of the process sending this traffic (The session ID of a process is the process group ID of the session leader). The parameter can be a list of such IDs, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands) defined within interfaces, not routers. FireHOL is "smart" enough to apply this parameter only to traffic send by the localhost, i.e. the replies of servers and requests of clients. It is not possible, and FireHOL will simply ignore this parameter, on traffic coming in or passign through the firewall host.


cmd <name>

command <name>

Description

cmd or command define the operating system command name of the process sending this traffic. The parameter can be a list of such command names, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands) defined within interfaces, not routers. FireHOL is "smart" enough to apply this parameter only to traffic send by the localhost, i.e. the replies of servers and requests of clients. It is not possible, and FireHOL will simply ignore this parameter, on traffic coming in or passign through the firewall host.


mac [not] <address>

Description

mac matches the source MAC address of packets comming into the firewall. The mac parameter does nothing for outgoing traffic.
For interfaces, the mac parameter matches against all traffic that comes into the firewall, whether it is server or client traffic.
For routers, the mac parameter matches also against all traffic comming into the firewall, but firehol considers the router input differently based on the command given. For server or route statements, the mac parameter matches the MAC address of the client (the host sending the request), while for client statements it matches the source MAC address of the server (the host accepting requests).

In principle, the mac parameter behaves the same for both interfaces and routers and this is why: The mac parameter matches the source MAC address of what FireHOL considers the "remote" host, not the one that FireHOL considers the "protected" one. For interfaces, this is simple, because always the "remote" host is a remote host and the "protected" host is the one running the firewall. For routers though, the command chosen (client or server) defines what the firewall protects. Therefore, a client statement protects the client making the "remote" host the server, while a server statement protects the server and therefore the "remote" host is the client.

More than one MAC addresses can be given if separated by spaces and enclosed in quotes as a single argument to the mac parameter.

The not argument will reverse the match. In case there are many MAC addresses defined, positive expressions are ORed (either address should be matched), while negative expressions are ANDed (none of the addresses should be matched).


mark [not] <ID>

Description

mark matches the traffic against the given IDs. This command accepts anything iptables accepts as MARKs (see iptables -m mark --help).

More than one MARK IDs can be given if separated by spaces and enclosed in quotes as a single argument to the mark parameter.


tos [not] <ID>

Description

tos matches the traffic against the given IDs. This command accepts anything iptables accepts as TOS (see iptables -m tos --help).

More than one IDs can be given if separated by spaces and enclosed in quotes as a single argument to the tos parameter.


dscp [not] <ID>


dscp [not] class <ID>

Description

dscp matches the traffic against the given DSCP IDs. This command accepts anything iptables accepts as DSCP (see iptables -m dscp --help).

More than one IDs can be given if separated by spaces and enclosed in quotes as a single argument.

Variables that control FireHOL

DEFAULT_INTERFACE_POLICY

Description

DEFAULT_INTERFACE_POLICY controls the default action to be taken on traffic not matched by any rule within an interface. Actually, this is a global setting for what policy does for an interface.

All packets that reach the end of an interface are logged only if the action is not return or accept. You can control the frequency of this logging by altering the frequency loglimit uses.

Default: DEFAULT_INTERFACE_POLICY="DROP"

Example: DEFAULT_INTERFACE_POLICY="REJECT"


DEFAULT_ROUTER_POLICY

Description

DEFAULT_ROUTER_POLICY controls the default action to be taken on traffic not matched by any rule within a router. Actually, this is a global setting for what policy does for a router.

All packets that reach the end of a router are logged only if the action is not return or accept. You can control the frequency of this logging by altering the frequency loglimit uses.

Default: DEFAULT_ROUTER_POLICY="RETURN"

Example: DEFAULT_ROUTER_POLICY="REJECT"


UNMATCHED_INPUT_POLICY

UNMATCHED_OUTPUT_POLICY

UNMATCHED_ROUTER_POLICY

Description

UNMATCHED_INPUT_POLICY controls the default action to be taken for incoming traffic not matched by any interface command.
UNMATCHED_OUTPUT_POLICY controls the default action to be taken for outgoing traffic not matched by any interface command.
UNMATCHED_ROUTER_POLICY controls the default action to be taken for forwarded traffic not matched by any router command.

All variables accept all the Actions FireHOL supports.

All packets that reach the end of firewall in all three chains are logged (always, regardless of these settings). You can control the frequency of this logging by altering the frequency loglimit uses.

Default: UNMATCHED_INPUT_POLICY="DROP"
Default: UNMATCHED_OUTPUT_POLICY="DROP"
Default: UNMATCHED_ROUTER_POLICY="DROP"

Example: UNMATCHED_INPUT_POLICY="REJECT"
Example: UNMATCHED_OUTPUT_POLICY="REJECT"
Example: UNMATCHED_ROUTER_POLICY="REJECT"


FIREHOL_INPUT_ACTIVATION_POLICY

FIREHOL_OUTPUT_ACTIVATION_POLICY

FIREHOL_FORWARD_ACTIVATION_POLICY

Description

All these variables have been added in v1.133

FIREHOL_INPUT_ACTIVATION_POLICY controls the default action to be taken for incoming traffic during firewall activation.
FIREHOL_OUTPUT_ACTIVATION_POLICY controls the default action to be taken for outgoing traffic during firewall activation.
FIREHOL_FORWARD_ACTIVATION_POLICY controls the default action to be taken for forwarded traffic during firewall activation.

All variables accept either ACCEPT, DROP or REJECT.

The default is ACCEPT in order to prevent a denial of service during a firewall restart. This is by design correct, since FireHOL will block all invalid connections after the firewall is fully activated (remember that FireHOL allows specific traffic to pass in both directions of the firewall).

Default: FIREHOL_INPUT_ACTIVATION_POLICY="ACCEPT"
Default: FIREHOL_OUTPUT_ACTIVATION_POLICY="ACCEPT"
Default: FIREHOL_FORWARD_ACTIVATION_POLICY="ACCEPT"

Example: FIREHOL_INPUT_ACTIVATION_POLICY="REJECT"
Example: FIREHOL_OUTPUT_ACTIVATION_POLICY="REJECT"
Example: FIREHOL_FORWARD_ACTIVATION_POLICY="REJECT"


FIREHOL_LOG_MODE

FIREHOL_LOG_LEVEL

FIREHOL_LOG_OPTIONS

FIREHOL_LOG_FREQUENCY

FIREHOL_LOG_BURST

FIREHOL_LOG_PREFIX

Description

FIREHOL_LOG_MODE controls the method of logging used by FireHOL. Currently, two modes are supported: LOG and ULOG. FIREHOL_LOG_LEVEL controls the level at which iptables will log things to the syslog. For a description of the possible values supported and for per-rule control of log level, see the log optional rule parameter. FIREHOL_LOG_LEVEL is ignored when FIREHOL_LOG_MODE=ULOG.

FIREHOL_LOG_OPTIONS controls the way iptables will log things to the syslog. The value of this variable is passed as is to iptables, so use exact iptables parameters. This variable can have special arguments for the LOG or ULOG actions of iptables.

FIREHOL_LOG_FREQUENCY and FIREHOL_LOG_BURST (added in v1.39 of FireHOL) control the frequency at each each logging rule will write packets to the syslog. FIREHOL_LOG_FREQUENCY is set to the maximum average frequency and FIREHOL_LOG_BURST specifies the maximum initial number of packets to match.

FIREHOL_LOG_PREFIX adds its contents to every log line, so that FireHOL logs can easily be detected in the system log. By default it is empty.

Default: FIREHOL_LOG_MODE="LOG"
Default: FIREHOL_LOG_OPTIONS="--log-level warning"
Default: FIREHOL_LOG_FREQUENCY="1/second"
Default: FIREHOL_LOG_BURST="5"
Default: FIREHOL_LOG_PREFIX=""

Example: FIREHOL_LOG_OPTIONS="--log-level info --log-tcp-options --log-ip-options"
Example: FIREHOL_LOG_FREQUENCY="30/minute"
Example: FIREHOL_LOG_BURST="2"
Example: FIREHOL_LOG_PREFIX="FIREHOL: "

To see the available iptables log options, run /sbin/iptables -j LOG --help or /sbin/iptables -j ULOG --help (depending on FIREHOL_LOG_MODE)
To see what iptables accepts as frequencies and bursts run, /sbin/iptables -m limit --help
You can also check man iptables.


FIREHOL_DROP_INVALID

Description

If FIREHOL_DROP_INVALID is set to 1, FireHOL will drop all packets that are matched by the INVALID state of the iptables connection tracker. The default in versions prior to v1.183 was to drop all those packers. The new default is not to drop those packets globally, but only as part of the protection statement.

See also Bug 927509 that discusses the effects of globally dropping invalid packets.

Default: FIREHOL_DROP_INVALID="0"
Example: FIREHOL_DROP_INVALID="1"


DEFAULT_CLIENT_PORTS

Description

DEFAULT_CLIENT_PORTS controls the port range to be used when a remote client is specified. For localhost clients, FireHOL finds the exact client ports by querying the kernel options.

Default: DEFAULT_CLIENT_PORTS="1024:65535"
Example: DEFAULT_CLIENT_PORTS="0:65535"


FIREHOL_NAT

Description

If FIREHOL_NAT is set to 1, FireHOL will load NAT kernel modules for those services that they are require such. FireHOL sets this to 1 automatically if you use the Helper Commands that do NAT.

Default: FIREHOL_NAT="0"
Example: FIREHOL_NAT="1"


FIREHOL_AUTOSAVE

Description

FIREHOL_AUTOSAVE controls the file that will be created when FireHOL is called with the save command line argument. If this variable is empty (the default), FireHOL will try to detect where to save the file. Currently, the RedHat way (/etc/sysconfig/iptables) and the Debian way (/var/lib/iptables/autosave) are automatically detected (in the order given here) based on the existance of the directory this file should be created in.

Default: FIREHOL_AUTOSAVE=""
Example: FIREHOL_AUTOSAVE="/tmp/firehol-saved.txt"


FIREHOL_LOAD_KERNEL_MODULES

Description

FIREHOL_LOAD_KERNEL_MODULES controls the way FireHOL handles required kernel modules. If set to 0 (zero), FireHOL will not attempt to load kernel modules at all. Set this to 0 (zero) if you have compiled a kernel that has all the modules build into it.

Since v1.165 of the FireHOL this feature is almost useless. FireHOL now tries to find the .config file of your kernel (in /proc/config or /lib/modules/`uname -r`/build/.config or /usr/src/linux/.config, in this order) and figures out which kernel modules are compiled build-in and which are modules.
So, this variable is only used in cases where FireHOL has no access at all to kernel configuration.

Keep in mind, that FireHOL is able to detect the ip_tables and ip_conntrack modules by examining the relative entries in /proc, so it can detect whether these are loaded without the need for the kernel configuration.

Default: FIREHOL_LOAD_KERNEL_MODULES=1
Example: FIREHOL_LOAD_KERNEL_MODULES=0


FIREHOL_TRUST_LOOPBACK

Description

FIREHOL_TRUST_LOOPBACK allows you to choose if FireHOL will trust the lo interface and accept all traffic to or from it (although not FORWARD, it matches only INPUT and OUTPUT).

The default is to accept all traffic from/to lo. If however you need to control what the local system users can use on the local machine, you can set this to anything other than 1 allowing you to setup the firewall as you will.

IMPORTANT: If you choose not to trust interface lo and you don't specifically setup the lo interface in firehol.conf, no local process will be able to communicate to any other local process, which most likely will break several things. Be sure you know what you are doing.

This option appeared in FireHOL version 1.195.

Default: FIREHOL_TRUST_LOOPBACK=1
Example: FIREHOL_TRUST_LOOPBACK=0


FIREHOL_DROP_ORPHAN_TCP_ACK_FIN

Description

FIREHOL_DROP_ORPHAN_TCP_ACK_FIN allows you to choose if FireHOL will drop all TCP connections with ACK FIN set without logging them. In busy environments the iptables connection tracker removes from the connection tracking list entries when it receives a FIN. This makes the ACK FIN appear as an invalid packet (it does not match anything on the connection tracking list, and it is not a new connection). Normally FireHOL logs this traffic. If FIREHOL_DROP_ORPHAN_TCP_ACK_FIN is set to 1, FireHOL will silentrly drop such packets.

Default: FIREHOL_DROP_ORPHAN_TCP_ACK_FIN=0
Example: FIREHOL_DROP_ORPHAN_TCP_ACK_FIN=1

Variables that FireHOL offers

RESERVED_IPS

Description

This variable includes all the IP addresses defined as IANA - Reserved by IANA. You can overwrite the internal default definion of this variable by creating a file with same name in /etc/firehol. This file accepts an IP definition per line. The supplied get-iana.sh script creates this file by directly fetching this document.

Example: interface eth0 internet src not "${RESERVED_IPS}"


PRIVATE_IPS

Description

This variable includes all the IP addresses defined as Private or Test by RFC 3330. You can overwrite the internal default definion of this variable by creating a file with same name in /etc/firehol. This file accepts an IP definition per line.

Example: interface eth0 internet src not "${PRIVATE_IPS}"


UNROUTABLE_IPS

Description

This variable is both RESERVED_IPS and PRIVATE_IPS together. I suggest to use this variable on interfaces and routers accepting Internet traffic. You can overwrite the internal default definion of this variable by creating a file with same name in /etc/firehol. This file accepts an IP definition per line.

Example: interface eth0 internet src not "${UNROUTABLE_IPS}"


MULTICAST_IPS

Description

You can overwrite the internal default definion of this variable by creating a file with same name in /etc/firehol. This file accepts an IP definition per line.

Example: interface eth0 internet src not "${MULTICAST_IPS}"


SourceForge Logo $Id: commands.html,v 1.75 2010/06/07 15:44:09 ktsaou Exp $

FireHOL, a firewall for humans...
© Copyright 2004 Costa Tsaousis <costa@tsaousis.gr>