firehol-blacklist

title: firehol-blacklist(5)

text:
# firehol-blacklist(5)

## NAME
firehol-blacklist - set up a unidirectional or bidirectional blacklist

## SYNOPSIS
{ blacklist | blacklist4 | blacklist6 } [ type ] [ inface device ] [ log "text" ] [ nolog ] [ connlog "text" ] [ loglimit "text" ] [ accounting accounting_name ] ip... [ except rule-params [or rule-params [or ... ]]]

## DESCRIPTION
The blacklist helper command creates a blacklist for the ip list given (which can be in quotes or not).

If the type full or all is supplied (or no type at all), a bidirectional stateless blacklist will be generated. The firewall will REJECT all traffic going to the IP addresses and DROP all traffic coming from them.

If the type stateful is supplied, a bidirectional stateful blacklist will be generated. The firewall will REJECT all traffic going to the IP addresses and DROP all traffic coming from them.

The differences between full and stateful are:

1.

stateful is resource efficient, since only the packets that initiate connections are examined. Established connections will never be re-tested against the blacklist.

2.

when using full and an ipset is updated to match the IP of an established connection, this established connection will immediately be blocked too.

If the type input or him, her, it, this, these is supplied, a unidirectional stateful blacklist will be generated. Connections can be established to such IP addresses, but the IP addresses will not be able to connect to the firewall or hosts protected by it.

Using log (log every packet), connlog (log connections once), or loglimit (log packets according to global throttling settings), the text will be logged when matching packets are found.

Using nolog will disable logging for this rule.

Using inface, the blacklist will be created on the interface device only (this includes forwarded traffic).

accounting will update the NFACCT accounting with the name given.

If the keyword except is found, then all the parameters following it are rules to match packets that should excluded from the blacklist (i.e. they are a whitelist for this blacklist). See firehol-params(5) for more details.

Blacklists must be declared before the first router or interface.

IP Lists for abuse, malware, attacks, proxies, anonymizers, etc can be downloaded with the contrib/update-ipsets.sh script. Information about the supported IP Lists can be found at FireHOL IP Lists (http://iplists.firehol.org/)

## EXAMPLES

```
blacklist full 192.0.2.1 192.0.2.2
blacklist input "192.0.2.3 192.0.2.4"
blacklist full inface eth0 log "BADGUY" 192.0.1.1 192.0.1.2
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

FireHOL IP Lists (http://iplists.firehol.org/)

## AUTHORS
FireHOL Team.


firehol-classify

package: firehol

title: firehol-classify(5)

summary: client command

text:
# firehol-classify(5)

## NAME
firehol-client - client command

## SYNOPSIS
{ client | client46 } service action [rule-params]

client4 service action [rule-params]

client6 service action [rule-params]

## DESCRIPTION
The client subcommand defines a client of a service on an interface or router. Any rule-params given to a parent interface or router are inherited by the client, but are reversed.

For FireHOL a client is the source of a request. Even though this is more complex for some multi-socket services, to FireHOL a client always initiates the connection.

The service parameter is one of the supported service names from firehol-services(5). Multiple services may be specified, space delimited in quotes.

The action can be any of the actions listed in firehol-actions(5).

The rule-params define a set of rule parameters to further restrict the traffic that is matched to this service. See firehol-params(5) for more details.

Note

Writing client4 is equivalent to writing ipv4 client and ensures this subcommand is applied only in the IPv4 firewall rules.

Writing client6 is equivalent to writing ipv6 client and ensures this subcommand is applied only in the IPv6 firewall rules.

Writing client46 is equivalent to writing both client and ensures this subcommand is applied in both the IPv4 and IPv6 firewall rules; it cannot be used as part an interface or router that is IPv4 or IPv6 only.

The default client inherits its behaviour from the enclosing interface or router.

## EXAMPLES

```
client smtp accept
client "smtp pop3" accept
client smtp accept src 192.0.2.1
client smtp accept log "mail packet" src 192.0.2.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-modifiers(5) - ipv4/ipv6 selection

•

firehol-services(5) - services list

•

firehol-actions(5) - actions for rules

•

firehol-params(5) - optional rule parameters

•

firehol-server(5) - server subcommand

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.

branch: sisyphus


firehol-client

title: firehol-client(5)

summary: client command

text:
# firehol-client(5)

## NAME
firehol-client - client command

## SYNOPSIS
{ client | client46 } service action [rule-params]

client4 service action [rule-params]

client6 service action [rule-params]

## DESCRIPTION
The client subcommand defines a client of a service on an interface or router. Any rule-params given to a parent interface or router are inherited by the client, but are reversed.

For FireHOL a client is the source of a request. Even though this is more complex for some multi-socket services, to FireHOL a client always initiates the connection.

The service parameter is one of the supported service names from firehol-services(5). Multiple services may be specified, space delimited in quotes.

The action can be any of the actions listed in firehol-actions(5).

The rule-params define a set of rule parameters to further restrict the traffic that is matched to this service. See firehol-params(5) for more details.

Note

Writing client4 is equivalent to writing ipv4 client and ensures this subcommand is applied only in the IPv4 firewall rules.

Writing client6 is equivalent to writing ipv6 client and ensures this subcommand is applied only in the IPv6 firewall rules.

Writing client46 is equivalent to writing both client and ensures this subcommand is applied in both the IPv4 and IPv6 firewall rules; it cannot be used as part an interface or router that is IPv4 or IPv6 only.

The default client inherits its behaviour from the enclosing interface or router.

## EXAMPLES

```
client smtp accept
client "smtp pop3" accept
client smtp accept src 192.0.2.1
client smtp accept log "mail packet" src 192.0.2.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-modifiers(5) - ipv4/ipv6 selection

•

firehol-services(5) - services list

•

firehol-actions(5) - actions for rules

•

firehol-params(5) - optional rule parameters

•

firehol-server(5) - server subcommand

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-conf

title: firehol-conf(5)

text:
# firehol-conf(5)

## NAME
firehol-connmark - set a stateful mark from the connmark group

## SYNOPSIS
{ connmark | connmark46 } value chain rule-params

connmark4 value chain rule-params

connmark6 value chain rule-params

## DESCRIPTION
Marks on packets can be matched by traffic shaping, routing, and firewall rules for controlling traffic.

Note Behaviour changed significantly in FireHOL v3 compared to earlier versions

FireHOL uses iptables masks to break the single 32-bit integer mark value into smaller groups and allows you to set and match them independently. The markdef group definitions to set this up are found in firehol-defaults.conf

The connmark helper command sets values within the connmark group. You can set value between 0 (no mark) and size-1. The default size for connmark is 64, so 63 is highest value possible. The default connmark types are stateful+permanent, meaning the initial match will only be done on NEW packets and the mark will be restored to all packets in the connection.

The chain will be used to find traffic to mark. It can be any of the iptables(8) built in chains belonging to the mangle table. The chain names are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. The names are case-sensitive.

The rule-params define a set of rule parameters to match the traffic that is to be marked within the chosen chain. See firehol-params(5) for more details.

Any connmark commands must be declared before the first router or interface.

Note

If you want to do policy based routing based on iptables(8) marks, you will need to disable the Root Path Filtering on the interfaces involved (rp_filter in sysctl).

FireQOS will read the FireHOL mark definitions and set up suitable offsets and marks for the various groups. If you are using a different tool, you should look at the emitted firewall to determine the final masks and values to use.

## EXAMPLES

```
 # mark with 1, packets sent by the local machine
 connmark 1 OUTPUT
 # mark with 2, packets routed by the local machine
 connmark 2 FORWARD
 # mark with 3, packets routed by the local machine, sent from
 #              192.0.2.2 destined for port TCP/25 of 198.51.100.1
 connmark 3 FORWARD proto tcp dport 25 dst 198.51.100.1 src 192.0.2.2
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

[firehol-mark(5)][keyword-firehol-mark] - set a stateful mark from the usermark group

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

ip(8) - show / manipulate routing, devices, policy routing and tunnels

•

FireHOL Website (http://firehol.org/)

•

Working With Marks Wiki Page (https://github.com/firehol/firehol/wiki/Working-with-MARKs)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

Linux Advanced Routing & Traffic Control HOWTO (http://lartc.org/howto/) is variable includes all the IP addresses defined by IANA (http://www.iana.org/) as reserved.

You can override the default values by creating a file called /etc/firehol/RESERVED_IPS.

Now that IPv4 address space has all been allocated there is very little reason that this value will need to change in future.

MULTICAST_IPS

This variable includes all the IP addresses defined as Multicast by RFC 3330 (https://tools.ietf.org/html/rfc3330).

You can override the default values by creating a file called /etc/firehol/MULTICAST_IPS.

## ADDING SERVICES
To define new services you add the appropriate lines before using them later in the configuration file.

The following are required:

server_myservice_ports="proto/sports"

client_myservice_ports="cports"

proto is anything iptables(8) accepts e.g. "tcp", "udp", "icmp", including numeric protocol values.

sports is the ports the server is listening at. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any server port.

cports is the ports the client may use to initiate a connection. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any client port. The keyword default will match default client ports. For the local machine (e.g. a client within an interface) it resolves to sysctl(8) variable net.ipv4.ip_local_port_range (or /proc/sys/net/ipv4/ip_local_port_range). For a remote machine (e.g. a client within an interface or anything in a router) it resolves to the variable DEFAULT_CLIENT_PORTS (see firehol-defaults.conf(5)).

The following are optional:

require_myservice_modules="modules"

require_myservice_nat_modules="nat-modules"

The named kernel modules will be loaded when the definition is used. The NAT modules will only be loaded if FIREHOL_NAT is non-zero (see firehol-defaults.conf(5)).

For example, for a service named daftnet that listens at two ports, port 1234 TCP and 1234 UDP where the expected client ports are the default random ports a system may choose, plus the same port numbers the server listens at, with further dynamic ports requiring kernel modules to be loaded:

```
    # Setup service
    server_daftnet_ports="tcp/1234 udp/1234"
    client_daftnet_ports="default 1234"
    require_daftnet_modules="ip_conntrack_daftnet"
    require_daftnet_nat_modules="ip_nat_daftnet

    interface eth0 lan0
      server daftnet accept

    interface eth1 lan1
      client daftnet reject

    router lan2lan inface eth0 outface eth1
      route daftnet accept
```

Where multiple ports are provides (as per the example), FireHOL simply determines all of the combinations of client and server ports and generates multiple iptables(8) statements to match them.

To create more complex rules, or stateless rules, you will need to create a bash function prefixed rules_ e.g. rules_myservice. The best reference is the many such functions in the main firehol(1) script.

When adding a service which uses modules, or via a custom function, you may also wish to include the following:

ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} myservice"

which will ensure your service is set-up correctly as part of the all service.

Note

To allow definitions to be shared you can instead create files and install them in the /etc/firehol/services directory with a .conf extension.

The first line must read:

```
#FHVER: 1:213
```

1 is the service definition API version. It will be changed if the API is ever modified. The 213 originally referred to a FireHOL 1.x minor version but is no longer checked.

FireHOL will refuse to run if the API version does not match the expected one.

## DEFINITIONS
•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

## SUBCOMMANDS
•

firehol-policy(5) - policy command

•

firehol-protection(5) - protection command

•

firehol-server(5) - server, route commands

•

firehol-client(5) - client command

•

firehol-group(5) - group command

## HELPER COMMANDS
These helpers can be used in interface and router definitions as well as before them:

•

firehol-iptables(5) - iptables helper

•

firehol-masquerade(5) - masquerade helper

This helper can be used in router definitions as well as before any router or interface:

•

firehol-tcpmss(5) - tcpmss helper

## CONFIGURATION HELPER COMMANDS
These helpers should only be used outside of interface and router definitions (i.e. before the first interface is defined).

•

firehol-version(5) - version config helper

•

firehol-action(5) - action config helper

•

firehol-blacklist(5) - blacklist config helper

•

firehol-classify(5) - classify config helper

•

firehol-connmark(5) - connmark config helper

•

firehol-dscp(5) - dscp config helper

•

firehol-mac(5) - mac config helper

•

firehol-mark(5) - mark config helper

•

firehol-nat(5) - nat, snat, dnat, redirect helpers

•

firehol-proxy(5) - transparent proxy/squid helpers

•

firehol-tos(5) - tos config helper

•

firehol-tosfix(5) - tosfix config helper

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol-defaults.conf(5) - control variables

•

firehol-services(5) - services list

•

firehol-actions(5) - actions for rules

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-connmark

title: firehol-connmark(5)

text:
# firehol-connmark(5)

## NAME
firehol-connmark - set a stateful mark from the connmark group

## SYNOPSIS
{ connmark | connmark46 } value chain rule-params

connmark4 value chain rule-params

connmark6 value chain rule-params

## DESCRIPTION
Marks on packets can be matched by traffic shaping, routing, and firewall rules for controlling traffic.

Note Behaviour changed significantly in FireHOL v3 compared to earlier versions

FireHOL uses iptables masks to break the single 32-bit integer mark value into smaller groups and allows you to set and match them independently. The markdef group definitions to set this up are found in firehol-defaults.conf

The connmark helper command sets values within the connmark group. You can set value between 0 (no mark) and size-1. The default size for connmark is 64, so 63 is highest value possible. The default connmark types are stateful+permanent, meaning the initial match will only be done on NEW packets and the mark will be restored to all packets in the connection.

The chain will be used to find traffic to mark. It can be any of the iptables(8) built in chains belonging to the mangle table. The chain names are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. The names are case-sensitive.

The rule-params define a set of rule parameters to match the traffic that is to be marked within the chosen chain. See firehol-params(5) for more details.

Any connmark commands must be declared before the first router or interface.

Note

If you want to do policy based routing based on iptables(8) marks, you will need to disable the Root Path Filtering on the interfaces involved (rp_filter in sysctl).

FireQOS will read the FireHOL mark definitions and set up suitable offsets and marks for the various groups. If you are using a different tool, you should look at the emitted firewall to determine the final masks and values to use.

## EXAMPLES

```
 # mark with 1, packets sent by the local machine
 connmark 1 OUTPUT
 # mark with 2, packets routed by the local machine
 connmark 2 FORWARD
 # mark with 3, packets routed by the local machine, sent from
 #              192.0.2.2 destined for port TCP/25 of 198.51.100.1
 connmark 3 FORWARD proto tcp dport 25 dst 198.51.100.1 src 192.0.2.2
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

[firehol-mark(5)][keyword-firehol-mark] - set a stateful mark from the usermark group

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

ip(8) - show / manipulate routing, devices, policy routing and tunnels

•

FireHOL Website (http://firehol.org/)

•

Working With Marks Wiki Page (https://github.com/firehol/firehol/wiki/Working-with-MARKs)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

Linux Advanced Routing & Traffic Control HOWTO (http://lartc.org/howto/) is variable includes all the IP addresses defined by IANA (http://www.iana.org/) as reserved.

You can override the default values by creating a file called /etc/firehol/RESERVED_IPS.

Now that IPv4 address space has all been allocated there is very little reason that this value will need to change in future.

MULTICAST_IPS

This variable includes all the IP addresses defined as Multicast by RFC 3330 (https://tools.ietf.org/html/rfc3330).

You can override the default values by creating a file called /etc/firehol/MULTICAST_IPS.

## ADDING SERVICES
To define new services you add the appropriate lines before using them later in the configuration file.

The following are required:

server_myservice_ports="proto/sports"

client_myservice_ports="cports"

proto is anything iptables(8) accepts e.g. "tcp", "udp", "icmp", including numeric protocol values.

sports is the ports the server is listening at. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any server port.

cports is the ports the client may use to initiate a connection. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any client port. The keyword default will match default client ports. For the local machine (e.g. a client within an interface) it resolves to sysctl(8) variable net.ipv4.ip_local_port_range (or /proc/sys/net/ipv4/ip_local_port_range). For a remote machine (e.g. a client within an interface or anything in a router) it resolves to the variable DEFAULT_CLIENT_PORTS (see firehol-defaults.conf(5)).

The following are optional:

require_myservice_modules="modules"

require_myservice_nat_modules="nat-modules"

The named kernel modules will be loaded when the definition is used. The NAT modules will only be loaded if FIREHOL_NAT is non-zero (see firehol-defaults.conf(5)).

For example, for a service named daftnet that listens at two ports, port 1234 TCP and 1234 UDP where the expected client ports are the default random ports a system may choose, plus the same port numbers the server listens at, with further dynamic ports requiring kernel modules to be loaded:

```
    # Setup service
    server_daftnet_ports="tcp/1234 udp/1234"
    client_daftnet_ports="default 1234"
    require_daftnet_modules="ip_conntrack_daftnet"
    require_daftnet_nat_modules="ip_nat_daftnet

    interface eth0 lan0
      server daftnet accept

    interface eth1 lan1
      client daftnet reject

    router lan2lan inface eth0 outface eth1
      route daftnet accept
```

Where multiple ports are provides (as per the example), FireHOL simply determines all of the combinations of client and server ports and generates multiple iptables(8) statements to match them.

To create more complex rules, or stateless rules, you will need to create a bash function prefixed rules_ e.g. rules_myservice. The best reference is the many such functions in the main firehol(1) script.

When adding a service which uses modules, or via a custom function, you may also wish to include the following:

ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} myservice"

which will ensure your service is set-up correctly as part of the all service.

Note

To allow definitions to be shared you can instead create files and install them in the /etc/firehol/services directory with a .conf extension.

The first line must read:

```
#FHVER: 1:213
```

1 is the service definition API version. It will be changed if the API is ever modified. The 213 originally referred to a FireHOL 1.x minor version but is no longer checked.

FireHOL will refuse to run if the API version does not match the expected one.

## DEFINITIONS
•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

## SUBCOMMANDS
•

firehol-policy(5) - policy command

•

firehol-protection(5) - protection command

•

firehol-server(5) - server, route commands

•

firehol-client(5) - client command

•

firehol-group(5) - group command

## HELPER COMMANDS
These helpers can be used in interface and router definitions as well as before them:

•

firehol-iptables(5) - iptables helper

•

firehol-masquerade(5) - masquerade helper

This helper can be used in router definitions as well as before any router or interface:

•

firehol-tcpmss(5) - tcpmss helper

## CONFIGURATION HELPER COMMANDS
These helpers should only be used outside of interface and router definitions (i.e. before the first interface is defined).

•

firehol-version(5) - version config helper

•

firehol-action(5) - action config helper

•

firehol-blacklist(5) - blacklist config helper

•

firehol-classify(5) - classify config helper

•

firehol-connmark(5) - connmark config helper

•

firehol-dscp(5) - dscp config helper

•

firehol-mac(5) - mac config helper

•

firehol-mark(5) - mark config helper

•

firehol-nat(5) - nat, snat, dnat, redirect helpers

•

firehol-proxy(5) - transparent proxy/squid helpers

•

firehol-tos(5) - tos config helper

•

firehol-tosfix(5) - tosfix config helper

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol-defaults.conf(5) - control variables

•

firehol-services(5) - services list

•

firehol-actions(5) - actions for rules

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-cthelper

title: firehol-cthelper(5)

summary: set the DSCP field in the packet header

text:
# firehol-cthelper(5)

## NAME
firehol-dscp - set the DSCP field in the packet header

## SYNOPSIS
dscp { value | class classid } chain rule-params

## DESCRIPTION
The dscp helper command sets the DSCP field in the header of packets traffic, to allow QoS shaping.

Note

There is also a dscp parameter which allows matching DSCP values within individual rules (see firehol-params(5)).

Set value to a decimal or hexadecimal (0xnn) number to set an explicit DSCP value or use class classid to use an iptables(8) DiffServ class, such as EF, BE, CSxx or AFxx (see iptables -j DSCP --help for more information).

The chain will be used to find traffic to mark. It can be any of the iptables(8) built in chains belonging to the mangle table. The chain names are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. The names are case-sensitive.

The rule-params define a set of rule parameters to match the traffic that is to be marked within the chosen chain. See firehol-params(5) for more details.

Any dscp commands will affect all traffic matched. They must be declared before the first router or interface.

## EXAMPLES

```
 # set DSCP field to 32, packets sent by the local machine
 dscp 32 OUTPUT
 # set DSCP field to 32 (hex 20), packets routed by the local machine
 dscp 0x20 FORWARD
 # set DSCP to DiffServ class EF, packets routed by the local machine
 #              and destined for port TCP/25 of 198.51.100.1
 dscp class EF FORWARD proto tcp dport 25 dst 198.51.100.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

ip(8) - show / manipulate routing, devices, policy routing and tunnels

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

Linux Advanced Routing & Traffic Control HOWTO (http://lartc.org/howto/)

## AUTHORS
FireHOL Team.


firehol-defaults-conf

title: firehol-defaults-conf(5)

text:
# firehol-defaults-conf(5)

## NAME
firehol-version - set version number of configuration file

## SYNOPSIS
version 6

## DESCRIPTION
The version helper command states the configuration file version.

If the value passed is newer than the running version of FireHOL supports, FireHOL will not run.

You do not have to specify a version number for a configuration file, but by doing so you will prevent FireHOL trying to process a file which it cannot handle.

The value that FireHOL expects is increased every time that the configuration file format changes.

Note

If you pass version 5 to FireHOL, it will disable IPv6 support and warn you that you must update your configuration.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-dscp

title: firehol-dscp(5)

summary: set the DSCP field in the packet header

text:
# firehol-dscp(5)

## NAME
firehol-dscp - set the DSCP field in the packet header

## SYNOPSIS
dscp { value | class classid } chain rule-params

## DESCRIPTION
The dscp helper command sets the DSCP field in the header of packets traffic, to allow QoS shaping.

Note

There is also a dscp parameter which allows matching DSCP values within individual rules (see firehol-params(5)).

Set value to a decimal or hexadecimal (0xnn) number to set an explicit DSCP value or use class classid to use an iptables(8) DiffServ class, such as EF, BE, CSxx or AFxx (see iptables -j DSCP --help for more information).

The chain will be used to find traffic to mark. It can be any of the iptables(8) built in chains belonging to the mangle table. The chain names are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. The names are case-sensitive.

The rule-params define a set of rule parameters to match the traffic that is to be marked within the chosen chain. See firehol-params(5) for more details.

Any dscp commands will affect all traffic matched. They must be declared before the first router or interface.

## EXAMPLES

```
 # set DSCP field to 32, packets sent by the local machine
 dscp 32 OUTPUT
 # set DSCP field to 32 (hex 20), packets routed by the local machine
 dscp 0x20 FORWARD
 # set DSCP to DiffServ class EF, packets routed by the local machine
 #              and destined for port TCP/25 of 198.51.100.1
 dscp class EF FORWARD proto tcp dport 25 dst 198.51.100.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

ip(8) - show / manipulate routing, devices, policy routing and tunnels

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

Linux Advanced Routing & Traffic Control HOWTO (http://lartc.org/howto/)

## AUTHORS
FireHOL Team.


firehol-group

title: firehol-group(5)

summary: group commands with common options

text:
# firehol-group(5)

## NAME
firehol-group - group commands with common options

## SYNOPSIS
group with rule-params

group end

## DESCRIPTION
The group command allows you to group together multiple client and server commands.

Grouping commands with common options (see firehol-params(5)) allows the option values to be checked only once in the generated firewall rather than once per service, making it more efficient.

Nested groups may be used.

## EXAMPLES
This:

```
interface any world
  client all accept
  server http accept
  # Provide these services to trusted hosts only
  server "ssh telnet" accept src "192.0.2.1 192.0.2.2"
```

can be replaced to produce a more efficient firewall by this:

```
interface any world
  client all accept
  server http accept
  # Provide these services to trusted hosts only
  group with src "192.0.2.1 192.0.2.2"
    server telnet accept
    server ssh accept
  group end
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-interface

title: firehol-interface(5)

summary: group commands with common options

text:
# firehol-interface(5)

## NAME
firehol-group - group commands with common options

## SYNOPSIS
group with rule-params

group end

## DESCRIPTION
The group command allows you to group together multiple client and server commands.

Grouping commands with common options (see [firehol-params(5)][]) allows the option values to be checked only once in the generated firewall rather than once per service, making it more efficient.

Nested groups may be used.

## EXAMPLES
This:

```
interface any world
  client all accept
  server http accept
  # Provide these services to trusted hosts only
  server "ssh telnet" accept src "192.0.2.1 192.0.2.2"
```

can be replaced to produce a more efficient firewall by this:

```
interface any world
  client all accept
  server http accept
  # Provide these services to trusted hosts only
  group with src "192.0.2.1 192.0.2.2"
    server telnet accept
    server ssh accept
  group end
```

## SEE ALSO
•

[firehol(1)][] - FireHOL program

•

[firehol.conf(5)][] - FireHOL configuration

•

[firehol-interface(5)][keyword-firehol-interface] - interface definition

•

[firehol-router(5)][keyword-firehol-router] - router definition

•

[firehol-params(5)][] - optional rule parameters

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-ipset

title: firehol-ipset(5)

summary: configure ipsets

text:
# firehol-ipset(5)

## NAME
firehol-ipset - configure ipsets

## SYNOPSIS
ipset command name options

## DESCRIPTION
FireHOL has an ipset helper. It is a wrapper around the real ipset command and is handled internally within FireHOL in such a way so that the ipset collections defined in the configuration will be activated before activating the firewall.

FireHOL is also smart enough to restore the ipsets after a reboot, before it restores the firewall, so that everything will work as seamlessly as possible.

The ipset helper has the same syntax with the real ipset command. So in FireHOL you just add the ipset statements you need, and FireHOL will do the rest.

Keep in mind that each ipset collection is either IPv4 or IPv6. In FireHOL prefix ipset with either ipv4 or ipv6 and FireHOL will choose the right IP version (there is also ipset4 and ipset6).

Also, do not add -! to ipset statements given in firehol.conf. FireHOL will batch import all ipsets and this option is not needed.

## FireHOL ipset extensions
The features below are extensions of ipset that can only be used from within firehol.conf. They will not work on a terminal.

The FireHOL helper allows mass import of ipset collections from files. This is done with ipset addfile command.

The ipset addfile command will get a filename, remove all comments (anything after a # on the same line), trim any empty lines and spaces, and add all the remaining lines to ipset, as if each line of the file was run with ipset add COLLECTION_NAME IP_FROM_FILE [other options].

The syntax of the ipset addfile command is:

```
 ipset addfile *name* [ip|net] *filename* [*other ipset add options*]
```

name is the collection to add the IPs.

ip is optional and will select all the lines of the file that do not contain a /.

net is optional and will select all the lines of the file that contain a /.

filename is the filename to read. You can give absolute filenames and relative filenames (to /etc/firehol).

other ipset add options is whatever else ipset add supports, that you are willing to give for each line.

The ipset add command implemented in FireHOL also allows you to give multiple IPs separated by comma or enclosed in quotes and separated by space.

## EXAMPLES

```
 ipv4 ipset create badguys hash:ip
 ipv4 ipset add badguys 1.2.3.4
 ipv4 ipset addfile badguys file-with-the-bad-guys-ips.txt
 ...
 ipv4 blacklist full ipset:badguys
 # example with multiple IPs
 ipv4 ipset create badguys hash:ip
 ipv4 ipset add badguys 1.2.3.4,5.6.7.8,9.10.11.12 # << comma separated
 ipv4 ipset add badguys "11.22.33.44 55.66.77.88"  # << space separated in quotes
```

ipsets with IP Lists for abuse, malware, attacks, proxies, anonymizers, etc can be downloaded with the contrib/update-ipsets.sh script. Information about the supported ipsets can be found at FireHOL IP Lists (http://iplists.firehol.org/)

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

FireHOL IP Lists (http://iplists.firehol.org/)

•

NAT HOWTO (http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO-6.html)

•

netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg)

## AUTHORS
FireHOL Team.


firehol-iptables

title: firehol-iptables(5)

summary: include custom iptables commands

text:
# firehol-iptables(5)

## NAME
firehol-iptables - include custom iptables commands

## SYNOPSIS
iptables argument...

ip6tables argument...

## DESCRIPTION
The iptables and ip6tables helper commands pass all of their arguments to the real iptables(8) or ip6tables(8) at the appropriate point during run-time.

Note

When used in an interface or router, the result will not have a direct relationship to the enclosing definition as the parameters passed are only those you supply.

You should not use /sbin/iptables or /sbin/ip6tables directly in a FireHOL configuration as they will run before FireHOL activates its firewall. This means that the commands are applied to the previously running firewall, not the new firewall, and will be lost when the new firewall is activated.

The iptables and ip6tables helpers are provided to allow you to hook in commands safely.

When using the -t option to specify a table, ensure this is the first option to iptables, otherwise "fast activation" will fail with an error message such as:

```
iptables-restore: The -t option cannot be used in iptables-restore
```

## EXAMPLES
Fix LXC DHCP on same host:

```
iptables -t mangle -A POSTROUTING -p udp --dport 68 -j CHECKSUM --checksum-fill
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-iptrap

title: firehol-iptrap(5)

text:
# firehol-iptrap(5)

## NAME
firehol-iptrap - dynamically put IP addresses in an ipset

## SYNOPSIS
{ iptrap | iptrap4 | iptrap6 } ipset type seconds [ timeout | counters ] [ method method ] [rule-params] [ except [rule-params] ]...

{ ipuntrap | ipuntrap4 | ipuntrap6 } ipset type [ timeout | counters ] [ method method ] [rule-params] [ except [rule-params] ]...

## DESCRIPTION
iptrap adds the IP addresses of the matching packets to ipset.

ipuntrap deletes the IP addresses of the matching packets from ipset.

Both helpers do not affect the flow of traffic. They do not ACCEPT, REJECT, DROP packets or affect the firewall in any way.

ipset is the name of the ipset to use.

type selects which of the IP addresses of the matching packets will be used (added or removed from the ipset). type can be src, dst, src,dst, dst,src, etc. If type is a pair, then the ipset must be an ipset of pairs too.

seconds is required by iptrap and gives the duration in seconds of the lifetime of each IP address that is added to ipset. Every matching packet will refresh this duration for the IP address in the ipset. The Linux kernel will automatically remove the IP from the ipset when this time expires. The user may monitor the remaining time for each IP, by running ipset list NAME (where NAME is the ipset parameter given in the iptrap command).

The seconds value default will not set any seconds. The ipset default will be used.

A seconds of 0 (zero), writes to the ipset permanently (this is a feature of the ipset command, not the ipset FireHOL helper).

The keywords timeout and counters are mutually exclusive. timeout is the default and means that each IP address every time is matched its timeout will be refreshed, while counters means that its packets and bytes counters will be refreshed. Unfortunately the kernel either re-add the IP in the ipset with the new timeout - but its counters will be lost, or just the counters will be updated, but the timeout will not be refreshed.

method is defines the storage method of the underlying ipset. It accepts all the types the ipset commands accepts.

method and type should match. For example if method is hash:ip then method should be either src or dst. If method is hash:ip,ip then method should be either src,dst or dst,src. If method is hash:ip,port,ip method should be src,src,dst or src,dst,dst or dst,src,src or dst,dst,src. For more information check the manual page of the ipset command.

The rule-params define a set of rule parameters to restrict the traffic that is matched to this helper. See firehol-params(5) for more details.

except rule-params are used to exclude traffic, i.e. traffic that normally is matched by the first set of rule-params, will be excluded if matched by the second.

iptrap and ipuntrap are hooked on PREROUTING so it is only useful for incoming traffic.

iptrap and ipuntrap cannot setup both IPv4 and IPv6 traps with one call. The reason is that the ipset can either be IPv4 or IPv6.

Both helpers will create the ipset specified, if that ipset is not already created by other statements. When the ipset is created by the iptrap helper, the ipset will not be reset (emptied) when the firewall is restarted.

The ipset options used when these helpers create ipsets can be controlled with the variable IPTRAP_DEFAULT_IPSET_OPTIONS.

## EXAMPLES

```
 # Example: mini-IDS
 # add to the ipset `trap` for an hour (3600 seconds) all IPs from all packets
 # coming from eth0 and going to tcp/3306 (mysql).
 iptrap4 src trap 3600 inface eth0 proto tcp dport 3306 log "TRAPPED HTTP"
 # block them
 blacklist4 full inface eth0 log "BLOCKED" src ipset:trap except src ipset:whitelist
 # Example: ipuntrap
 ipuntrap4 src trap inface eth0 src ipset:trap proto tcp dport 80 log "UNTRAPPED HTTP"
 # Example: a knock
 # The user will be able to knock at tcp/12345
 iptrap4 src knock1 30 inface eth0 proto tcp dport 12345 log "KNOCK STEP 1"
 # in 30 seconds knock at tcp/23456
 iptrap4 src knock2 60 inface eth0 proto tcp dport 23456 src ipset:knock1 log "KNOCK STEP 2"
 # in 60 seconds knock at tcp/34566
 iptrap4 src knock3 90 inface eth0 proto tcp dport 34567 src ipset:knock2 log "KNOCK STEP 3"
 #
 # and in 90 seconds ssh
 interface ...
     server ssh accept src ipset:knock3
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-mac

title: firehol-mac(5)

text:
# firehol-mac(5)

## NAME
firehol-mac - ensure source IP and source MAC address match

## SYNOPSIS
mac IP macaddr

## DESCRIPTION
Any mac commands will affect all traffic destined for the firewall host, or to be forwarded by the host. They must be declared before the first router or interface.

Note

There is also a mac parameter which allows matching MAC addresses within individual rules (see firehol-params(5)).

The mac helper command DROPs traffic from the IP address that was not sent using the macaddr specified.

When packets are dropped, a log is produced with the label "MAC MISSMATCH" (sic.). mac obeys the default log limits (see [LOGGING][] in firehol-params(5)).

Note

This command restricts an IP to a particular MAC address. The same MAC address is permitted send traffic with a different IP.

## EXAMPLES

```
mac 192.0.2.1    00:01:01:00:00:e6
mac 198.51.100.1 00:01:01:02:aa:e8
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-mark

title: firehol-mark(5)

text:
# firehol-mark(5)

## NAME
firehol-mac - ensure source IP and source MAC address match

## SYNOPSIS
mac IP macaddr

## DESCRIPTION
Any mac commands will affect all traffic destined for the firewall host, or to be forwarded by the host. They must be declared before the first router or interface.

Note

There is also a mac parameter which allows matching MAC addresses within individual rules (see firehol-params(5)).

The mac helper command DROPs traffic from the IP address that was not sent using the macaddr specified.

When packets are dropped, a log is produced with the label "MAC MISSMATCH" (sic.). mac obeys the default log limits (see [LOGGING][] in firehol-params(5)).

Note

This command restricts an IP to a particular MAC address. The same MAC address is permitted send traffic with a different IP.

## EXAMPLES

```
mac 192.0.2.1    00:01:01:00:00:e6
mac 198.51.100.1 00:01:01:02:aa:e8
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-masquerade

title: firehol-masquerade(5)

text:
# firehol-masquerade(5)

## NAME
firehol-masquerade - set up masquerading (NAT) on an interface

## SYNOPSIS
masquerade real-interface rule-params

masquerade [reverse] rule-params

## DESCRIPTION
The masquerade helper command sets up masquerading on the output of a real network interface (as opposed to a FireHOL interface definition).

If a real-interface is specified the command should be used before any interface or router definitions. Multiple values can be given separated by whitespace, so long as they are enclosed in quotes.

If used within an interface definition the definition's real-interface will be used.

If used within a router definition the definition's outface(s) will be used, if specified. If the reverse option is given, then the definition's inface(s) will be used, if specified.

Unlike most commands, masquerade does not inherit its parent definition's rule-params, it only honours its own. The inface and outface parameters should not be used (iptables(8) does not support inface in the POSTROUTING chain and outface will be overwritten by FireHOL using the rules above).

Note

The masquerade always applies to the output of the chosen network interfaces.

FIREHOL_NAT will be turned on automatically (see firehol-defaults.conf(5) ) and FireHOL will enable packet-forwarding in the kernel.

## MASQUERADING AND SNAT
Masquerading is a special form of Source NAT (SNAT) that changes the source of requests when they go out and replaces their original source when they come in. This way a Linux host 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 compare to SNAT because it checks the IP address of the outgoing interface every time for every packet. If your host has a static IP address you should generally prefer SNAT.

## EXAMPLES

```
 # Before any interface or router
 masquerade eth0 src 192.0.2.0/24 dst not 192.0.2.0/24
 # In an interface definition to masquerade the output of its real-interface
 masquerade
 # In a router definition to masquerade the output of its outface
 masquerade
 # In a router definition to masquerade the output of its inface
 masquerade reverse
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

firehol-nat(5) - nat, snat, dnat, redirect config helpers

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-modifiers

title: firehol-modifiers(5)

summary: set up NAT and port redirections

text:
# firehol-modifiers(5)

## NAME
firehol-nat - set up NAT and port redirections

## SYNOPSIS
{ nat to-destination | dnat [to] } ipaddr[:port] [random] [persistent] [id id] [at chain] [rule-params]

{ nat to-source | snat [to] } ipaddr[:port] [random] [persistent] [id id] [at chain] [rule-params]

{ nat redirect-to | redirect [to] } port[-range] [random] [id id] [at chain] [rule-params]

## DESCRIPTION
Destination NAT is provided by nat to-destination and its synonym dnat.

Source NAT is provided by nat to-source and its synonym snat.

Redirection to a port on the local host is provided by nat redirect-to and its synonym redirect.

The port part of the new address is optional with SNAT and DNAT; if not specified it will not be changed.

When you apply NAT to a packet, the Linux kernel will track the changes it makes, so that when it sees replies the transformation will be applied in the opposite direction. For instance if you changed the destination port of a packet from 80 to 8080, when a reply comes back, its source is set as 80. This means the original sender is not aware a transformation is happening.

This means that NAT is only applied on the first packet of each connection (the nat FireHOL helper always appends state NEW to NAT statements).

The NAT helper can be used to setup load balancing. Check the section BALANCING below.

Note

The rule-params are used only to determine the traffic that will be matched for NAT in these commands, not to permit traffic to flow.

Applying NAT does not automatically create rules to allow the traffic to pass. You will still need to include client or server entries in an interface or router to allow the traffic.

When using dnat or redirect, the transformation is in the PREROUTING chain of the NAT table and happens before normal rules are matched, so your client or server rule should match the "modified" traffic.

When using snat, the transformation is in the POSTROUTING chain of the NAT table and happens after normal rules are matched, so your client or server rule should match the "unmodified" traffic.

See the netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg) if you would like to see how network packets are processed by the kernel in detail.

The at keyword allows setting a different chain to attach the rules. For dnat and redirect the default is PREROUTING, but OUTPUT is also supported. For snat the default is POSTROUTING, but INPUT is also supported.

random will randomise the port mapping involved, to ensure the ports used are not predictable.

persistent is used when the statement is given alternatives (i.e. many destination servers for dnat, many source IPs for snat, many ports for redirect). It will attempt to keep each client on the same nat map. See below for more information about persistence.

The nat helper takes one of the following sub-commands:

to-destination ipaddr[:port]

Defines a Destination NAT (DNAT). Commonly thought of as port-forwarding (where packets destined for the firewall with a given port and protocol are sent to a different IP address and possibly port), DNAT is much more flexible in that any number of parameters can be matched before the destination information is rewritten.

ipaddr[:port] is the destination address to be set in packets matching rule-params.

If no rules are given, all forwarded traffic will be matched. outface should not be used in DNAT since the information is not available at the time the decision is made.

ipaddr[:port] accepts any --to-destination values that iptables(8) accepts. Run iptables -j DNAT --help for more information. Multiple ipaddr[:port] may be specified by separating with spaces and enclosing with quotes.

to-source ipaddr[:port]

Defines a Source NAT (SNAT). SNAT is similar to masquerading but is more efficient for static IP addresses. You can use it to give a public IP address to a host which does not have one behind the firewall. See also firehol-masquerade(5).

ipaddr[:port] is the source address to be set in packets matching rule-params.

If no rules are given, all forwarded traffic will be matched. inface should not be used in SNAT since the information is not available at the time the decision is made.

ipaddr[:port] accepts any --to-source values that iptables(8) accepts. Run iptables -j SNAT --help for more information. Multiple ipaddr[:port] may be specified by separating with spaces and enclosing with quotes.

redirect-to port[-range]

Redirect matching traffic to the local machine. This is typically useful if you want to intercept some traffic and process it on the local machine.

port[-range] is the port range (from-to) or single port that packets matching rule-params will be redirected to.

If no rules are given, all forwarded traffic will be matched. outface should not be used in REDIRECT since the information is not available at the time the decision is made.

## BALANCING
NAT can balance multiple servers (or IPs in case of snat) when a range is specified. This is handled by the kernel.

Example:

```
dnat4 to 10.0.0.1-10.0.0.10 persistent proto tcp dst 1.1.1.1 dport 80
```

In the above example, the Linux kernel will give a persistent server to all the sockets of any single client.

FireHOL can also setup balancing using a round-robin or weighted average distribution of requests. However persistent cannot be used (the Linux kernel applies persistence on a single NAT statement).

### Round Robin distribution
To enable round robin distribution, give multiple to values, space separated and enclosed in quotes, or comma separated.

Example:

```
 dnat4 to 10.0.0.1,10.0.0.2,10.0.0.3 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1 10.0.0.2 10.0.0.3" proto tcp dst 1.1.1.1 port 80
```

Ports can also be given per IP:

```
 dnat4 to 10.0.0.1:70,10.0.0.2:80,10.0.0.3:90 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1:70 10.0.0.2:80 10.0.0.3:90" proto tcp dst 1.1.1.1 port 80
```

### Weighted distribution
To enable weighted distribution, append a slash with the weight requested for each entry.

FireHOL adds all the weights given and calculates the percentage of traffic each entry should receive.

Example:

```
 dnat4 to 10.0.0.1/30,10.0.0.2/30,10.0.0.3/40 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1/30 10.0.0.2/30 10.0.0.3/40" proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to 10.0.0.1:70/30,10.0.0.2:80/30,10.0.0.3:90/40 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1:70/30 10.0.0.2:80/30 10.0.0.3:90/40" proto tcp dst 1.1.1.1 port 80
```

### PERSISTENCE
The kernel supports persistence only if the NAT alternatives are contiguous (i.e. dnat to A-B, snat to A-B, redirect to 1000:1010, etc). If they are contiguous, persistence is left at the kernel. FireHOL does nothing.

If the alternatives are not contiguous, FireHOL will use the recent iptables module to apply persistence itself.

FireHOL supports mixed mode persistence. For example, you can have something like this:

```
dnat to A-B/70,C-D/20,F/10 persistence id mybalancer
```

The above is a weighted distribution of persistence. Group A-B will get 70%, C-D 20% and server F 10%.

Using the above, FireHOL will apply its persistence to pick one of the groups A-B, or C-D, or F. Once the group has been picked by FireHOL, the kernel will apply persistence within the group, to pick the server that will handle the request.

The FireHOL persistence works like this:

1.

A packet is received that should be NATed

2.

A lookup is made using the recent module to find if it has been seen before. The source IP of packet is looked up.

3.

If it has been seen before, the connection is mapped the same way the last time was mapped. The recent module is updated too.

4.

If it has not been seen before, the connection is mapped using the distribution method specified. The recent module is updated too, to be ready for the next connection.

The recent module has a few limitations:

1.

It has lookup tables. We need one lookup table for each member of of the NAT. FireHOL uses the id parameter and the definition of each alternative in the NAT statement to form a name for the lookup table. These lookup tables are persistent to firewall restarts, this is why FireHOL requires from you to set an id.

2.

It can keep entries in its lookup tables for a given time. FireHOL sets this to 3600 seconds. You can control it by setting FIREHOL_NAT_PERSISTENCE_SECONDS.

3.

It has a limit on the number of entries in the lookup tables. FireHOL cannot set this. This is kernel module option. The default is 200 entries.

Check this:

~~~~ # modinfo xt_recent filename: /lib/modules/4.1.12-gentoo/kernel/net/netfilter/xt_recent.ko alias: ip6t_recent alias: ipt_recent license: GPL description: Xtables: "recently-seen" host matching author: Jan Engelhardt <jengelh@medozas.de> author: Patrick McHardy <kaber@trash.net> depends: x_tables intree: Y vermagic: 4.1.12-gentoo SMP preempt mod_unload modversions parm: ip_list_tot:number of IPs to remember per list (uint) parm: ip_list_hash_size:size of hash table used to look up IPs (uint) parm: ip_list_perms:permissions on /proc/net/xt_recent/* files (uint) parm: ip_list_uid:default owner of /proc/net/xt_recent/* files (uint) parm: ip_list_gid:default owning group of /proc/net/xt_recent/* files (uint) parm: ip_pkt_list_tot:number of packets per IP address to remember (max. 255) (uint) ~~~~

```
You have to consult your distribution documentation to set these.
You can find their current values by examining files found in
`/sys/module/xt_recent/parameters/` Unfortunately, these files
are not writable, so to change parameters you have unload and
reload the module (i.e. apply a firewall that does not use the
*recent* module, `rmmod xt_recent`, change the parameter,
re-apply a firewall that uses the *recent* module).
Normally, you will need a line in `/etc/modprobe.d/netfitler.conf`
like this:
~~~~
options xt_recent ip_list_tot=16384
~~~~
The number 16384 I used is the max number of unique client IPs
I expect to have per hour (`FIREHOL_NAT_PERSISTENCE_SECONDS`)
for this service.
`ip_list_hash_size` is calculated by kernel when the module
is loaded to be bigger and up to twice `ip_list_tot`.
```

Once you have the balancer running, you can find its lookup tables in /proc/net/xt_recent/. There you will find files starting with the id parameter, one file for every alternative of the NAT rule.

## EXAMPLES

```
 # Port forwarding HTTP
 dnat4 to 192.0.2.2 proto tcp dport 80
 # Port forwarding HTTPS on to a different port internally
 dnat4 to 192.0.2.2:4443 proto tcp dport 443
 # Fix source for traffic leaving the firewall via eth0 with private address
 snat4 to 198.51.100.1 outface eth0 src 192.168.0.0/24
 # Transparent squid (running on the firewall) for some hosts
 redirect4 to 8080 inface eth0 src 198.51.100.0/24 proto tcp dport 80
 # Send to 192.0.2.1
 #  - all traffic arriving at or passing through the firewall
 nat4 to-destination 192.0.2.1
 # Send to 192.0.2.1
 #  - all traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1
 nat4 to-destination 192.0.2.1 dst 203.0.113.1
 # Send to 192.0.2.1
 #  - TCP traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1
 nat4 to-destination 192.0.2.1 proto tcp dst 203.0.113.1
 # Send to 192.0.2.1
 #  - TCP traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1, port 25
 nat4 to-destination 192.0.2.1 proto tcp dport 25 dst 203.0.113.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

NAT HOWTO (http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO-6.html)

•

netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg)

## AUTHORS
FireHOL Team.


firehol-nat

title: firehol-nat(5)

summary: set up NAT and port redirections

text:
# firehol-nat(5)

## NAME
firehol-nat - set up NAT and port redirections

## SYNOPSIS
{ nat to-destination | dnat [to] } ipaddr[:port] [random] [persistent] [id id] [at chain] [rule-params]

{ nat to-source | snat [to] } ipaddr[:port] [random] [persistent] [id id] [at chain] [rule-params]

{ nat redirect-to | redirect [to] } port[-range] [random] [id id] [at chain] [rule-params]

## DESCRIPTION
Destination NAT is provided by nat to-destination and its synonym dnat.

Source NAT is provided by nat to-source and its synonym snat.

Redirection to a port on the local host is provided by nat redirect-to and its synonym redirect.

The port part of the new address is optional with SNAT and DNAT; if not specified it will not be changed.

When you apply NAT to a packet, the Linux kernel will track the changes it makes, so that when it sees replies the transformation will be applied in the opposite direction. For instance if you changed the destination port of a packet from 80 to 8080, when a reply comes back, its source is set as 80. This means the original sender is not aware a transformation is happening.

This means that NAT is only applied on the first packet of each connection (the nat FireHOL helper always appends state NEW to NAT statements).

The NAT helper can be used to setup load balancing. Check the section BALANCING below.

Note

The rule-params are used only to determine the traffic that will be matched for NAT in these commands, not to permit traffic to flow.

Applying NAT does not automatically create rules to allow the traffic to pass. You will still need to include client or server entries in an interface or router to allow the traffic.

When using dnat or redirect, the transformation is in the PREROUTING chain of the NAT table and happens before normal rules are matched, so your client or server rule should match the "modified" traffic.

When using snat, the transformation is in the POSTROUTING chain of the NAT table and happens after normal rules are matched, so your client or server rule should match the "unmodified" traffic.

See the netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg) if you would like to see how network packets are processed by the kernel in detail.

The at keyword allows setting a different chain to attach the rules. For dnat and redirect the default is PREROUTING, but OUTPUT is also supported. For snat the default is POSTROUTING, but INPUT is also supported.

random will randomise the port mapping involved, to ensure the ports used are not predictable.

persistent is used when the statement is given alternatives (i.e. many destination servers for dnat, many source IPs for snat, many ports for redirect). It will attempt to keep each client on the same nat map. See below for more information about persistence.

The nat helper takes one of the following sub-commands:

to-destination ipaddr[:port]

Defines a Destination NAT (DNAT). Commonly thought of as port-forwarding (where packets destined for the firewall with a given port and protocol are sent to a different IP address and possibly port), DNAT is much more flexible in that any number of parameters can be matched before the destination information is rewritten.

ipaddr[:port] is the destination address to be set in packets matching rule-params.

If no rules are given, all forwarded traffic will be matched. outface should not be used in DNAT since the information is not available at the time the decision is made.

ipaddr[:port] accepts any --to-destination values that iptables(8) accepts. Run iptables -j DNAT --help for more information. Multiple ipaddr[:port] may be specified by separating with spaces and enclosing with quotes.

to-source ipaddr[:port]

Defines a Source NAT (SNAT). SNAT is similar to masquerading but is more efficient for static IP addresses. You can use it to give a public IP address to a host which does not have one behind the firewall. See also firehol-masquerade(5).

ipaddr[:port] is the source address to be set in packets matching rule-params.

If no rules are given, all forwarded traffic will be matched. inface should not be used in SNAT since the information is not available at the time the decision is made.

ipaddr[:port] accepts any --to-source values that iptables(8) accepts. Run iptables -j SNAT --help for more information. Multiple ipaddr[:port] may be specified by separating with spaces and enclosing with quotes.

redirect-to port[-range]

Redirect matching traffic to the local machine. This is typically useful if you want to intercept some traffic and process it on the local machine.

port[-range] is the port range (from-to) or single port that packets matching rule-params will be redirected to.

If no rules are given, all forwarded traffic will be matched. outface should not be used in REDIRECT since the information is not available at the time the decision is made.

## BALANCING
NAT can balance multiple servers (or IPs in case of snat) when a range is specified. This is handled by the kernel.

Example:

```
dnat4 to 10.0.0.1-10.0.0.10 persistent proto tcp dst 1.1.1.1 dport 80
```

In the above example, the Linux kernel will give a persistent server to all the sockets of any single client.

FireHOL can also setup balancing using a round-robin or weighted average distribution of requests. However persistent cannot be used (the Linux kernel applies persistence on a single NAT statement).

### Round Robin distribution
To enable round robin distribution, give multiple to values, space separated and enclosed in quotes, or comma separated.

Example:

```
 dnat4 to 10.0.0.1,10.0.0.2,10.0.0.3 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1 10.0.0.2 10.0.0.3" proto tcp dst 1.1.1.1 port 80
```

Ports can also be given per IP:

```
 dnat4 to 10.0.0.1:70,10.0.0.2:80,10.0.0.3:90 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1:70 10.0.0.2:80 10.0.0.3:90" proto tcp dst 1.1.1.1 port 80
```

### Weighted distribution
To enable weighted distribution, append a slash with the weight requested for each entry.

FireHOL adds all the weights given and calculates the percentage of traffic each entry should receive.

Example:

```
 dnat4 to 10.0.0.1/30,10.0.0.2/30,10.0.0.3/40 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1/30 10.0.0.2/30 10.0.0.3/40" proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to 10.0.0.1:70/30,10.0.0.2:80/30,10.0.0.3:90/40 proto tcp dst 1.1.1.1 port 80
 # or
 dnat4 to "10.0.0.1:70/30 10.0.0.2:80/30 10.0.0.3:90/40" proto tcp dst 1.1.1.1 port 80
```

### PERSISTENCE
The kernel supports persistence only if the NAT alternatives are contiguous (i.e. dnat to A-B, snat to A-B, redirect to 1000:1010, etc). If they are contiguous, persistence is left at the kernel. FireHOL does nothing.

If the alternatives are not contiguous, FireHOL will use the recent iptables module to apply persistence itself.

FireHOL supports mixed mode persistence. For example, you can have something like this:

```
dnat to A-B/70,C-D/20,F/10 persistence id mybalancer
```

The above is a weighted distribution of persistence. Group A-B will get 70%, C-D 20% and server F 10%.

Using the above, FireHOL will apply its persistence to pick one of the groups A-B, or C-D, or F. Once the group has been picked by FireHOL, the kernel will apply persistence within the group, to pick the server that will handle the request.

The FireHOL persistence works like this:

1.

A packet is received that should be NATed

2.

A lookup is made using the recent module to find if it has been seen before. The source IP of packet is looked up.

3.

If it has been seen before, the connection is mapped the same way the last time was mapped. The recent module is updated too.

4.

If it has not been seen before, the connection is mapped using the distribution method specified. The recent module is updated too, to be ready for the next connection.

The recent module has a few limitations:

1.

It has lookup tables. We need one lookup table for each member of of the NAT. FireHOL uses the id parameter and the definition of each alternative in the NAT statement to form a name for the lookup table. These lookup tables are persistent to firewall restarts, this is why FireHOL requires from you to set an id.

2.

It can keep entries in its lookup tables for a given time. FireHOL sets this to 3600 seconds. You can control it by setting FIREHOL_NAT_PERSISTENCE_SECONDS.

3.

It has a limit on the number of entries in the lookup tables. FireHOL cannot set this. This is kernel module option. The default is 200 entries.

Check this:

~~~~ # modinfo xt_recent filename: /lib/modules/4.1.12-gentoo/kernel/net/netfilter/xt_recent.ko alias: ip6t_recent alias: ipt_recent license: GPL description: Xtables: "recently-seen" host matching author: Jan Engelhardt <jengelh@medozas.de> author: Patrick McHardy <kaber@trash.net> depends: x_tables intree: Y vermagic: 4.1.12-gentoo SMP preempt mod_unload modversions parm: ip_list_tot:number of IPs to remember per list (uint) parm: ip_list_hash_size:size of hash table used to look up IPs (uint) parm: ip_list_perms:permissions on /proc/net/xt_recent/* files (uint) parm: ip_list_uid:default owner of /proc/net/xt_recent/* files (uint) parm: ip_list_gid:default owning group of /proc/net/xt_recent/* files (uint) parm: ip_pkt_list_tot:number of packets per IP address to remember (max. 255) (uint) ~~~~

```
You have to consult your distribution documentation to set these.
You can find their current values by examining files found in
`/sys/module/xt_recent/parameters/` Unfortunately, these files
are not writable, so to change parameters you have unload and
reload the module (i.e. apply a firewall that does not use the
*recent* module, `rmmod xt_recent`, change the parameter,
re-apply a firewall that uses the *recent* module).
Normally, you will need a line in `/etc/modprobe.d/netfitler.conf`
like this:
~~~~
options xt_recent ip_list_tot=16384
~~~~
The number 16384 I used is the max number of unique client IPs
I expect to have per hour (`FIREHOL_NAT_PERSISTENCE_SECONDS`)
for this service.
`ip_list_hash_size` is calculated by kernel when the module
is loaded to be bigger and up to twice `ip_list_tot`.
```

Once you have the balancer running, you can find its lookup tables in /proc/net/xt_recent/. There you will find files starting with the id parameter, one file for every alternative of the NAT rule.

## EXAMPLES

```
 # Port forwarding HTTP
 dnat4 to 192.0.2.2 proto tcp dport 80
 # Port forwarding HTTPS on to a different port internally
 dnat4 to 192.0.2.2:4443 proto tcp dport 443
 # Fix source for traffic leaving the firewall via eth0 with private address
 snat4 to 198.51.100.1 outface eth0 src 192.168.0.0/24
 # Transparent squid (running on the firewall) for some hosts
 redirect4 to 8080 inface eth0 src 198.51.100.0/24 proto tcp dport 80
 # Send to 192.0.2.1
 #  - all traffic arriving at or passing through the firewall
 nat4 to-destination 192.0.2.1
 # Send to 192.0.2.1
 #  - all traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1
 nat4 to-destination 192.0.2.1 dst 203.0.113.1
 # Send to 192.0.2.1
 #  - TCP traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1
 nat4 to-destination 192.0.2.1 proto tcp dst 203.0.113.1
 # Send to 192.0.2.1
 #  - TCP traffic arriving at or passing through the firewall
 #  - which WAS going to 203.0.113.1, port 25
 nat4 to-destination 192.0.2.1 proto tcp dport 25 dst 203.0.113.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

NAT HOWTO (http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO-6.html)

•

netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg)

## AUTHORS
FireHOL Team.


firehol-params

title: firehol-params(5)

summary: optional rule parameters

text:
# firehol-params(5)

## NAME
firehol-params - optional rule parameters

## SYNOPSIS
Common

{ src | src4 | src6 } [not] host

{ dst | dst4 | dst6 } [not] host

srctype [not] type

dsttype [not] type

proto [not] protocol

mac [not] macaddr

dscp [not] value class classid

mark [not] id

connmark [not] id

custommark [not] name id

rawmark [not] id

tos [not] id

custom "iptables-options..."

custom-in "iptables-options..."

custom-out "iptables-options..."

Router Only

inface [not] interface

outface [not] interface

physin [not] interface

physout [not] interface

Interface Only

uid [not] user

gid [not] group

Logging

connlog "log text"

log "log text" [level loglevel]

loglimit "log text" [level loglevel]

Helpers Only

sport port

dport port

state state

ipset [not] name flags [no-counters] [bytes-lt|bytes-eq|bytes-gt|bytes-not-eq number] [packets-lt|packets-eq|packets-gt|packets-not-eq number] [options custom-ipset-options]

limit limit burst

connlimit upto|above limit [mask mask] [saddr|daddr]

hashlimit name upto|above amount/period [burst amount] [mode {srcip|srcport|dstip|dstport},...] [srcmask prefix] [dstmask prefix] [htable-size buckets] [htable-max entries] [htable-expire msec] [htable-gcinterval msec]

## DESCRIPTION
Optional rule parameters are accepted by many commands to narrow the match they make. Not all parameters are accepted by all commands so you should check the individual commands for exclusions.

All matches are made against the REQUEST. FireHOL automatically sets up the necessary stateful rules to deal with replies in the reverse direction.

All matches should be true for a statement to be executed. However, many matches support multiple values. In this case, at least one of the values must match.

Example:

```
server smtp accept src 1.1.1.1 dst 2.2.2.2
```

In the above example all smtp requests coming in from 1.1.1.1 and going out to smtp server 2.2.2.2 will be matched.

```
server smtp accept src 1.1.1.1 dst 2.2.2.2,3.3.3.3
```

In the above example all smtp requests coming in from 1.1.1.1 and going out to either smtp server 2.2.2.2 or 3.3.3.3 will be matched.

Use the keyword not to match any value other than the one(s) specified.

The logging parameters are unusual in that they do not affect the match, they just cause a log message to be emitted. Therefore, the logging parameters don't support the not option.

FireHOL is designed so that if you specify a parameter that is also used internally by the command then a warning will be issued (and the internal version will be used).

## COMMON

### src, dst
Use src and dst to define the source and destination IP addresses of the request respectively. host defines the IP or IPs to be matched.

host can also refer to an ipset, using this syntax: ipset:NAME, where NAME is the name of the ipset. The ipset has to be of type hash:ip for this match to work. The source IP or the destination IP will be used for the match, depending if the ipset is given as src or dst.

IPs and ipsets can be mixed together, like this: src 1.1.1.1,ipset:NAME1,2.2.2.2,ipset:NAME2

Examples:

```
server4 smtp accept src not 192.0.2.1
server4 smtp accept dst 198.51.100.1
server4 smtp accept src not 192.0.2.1 dst 198.51.100.1
server6 smtp accept src not 2001:DB8:1::/64
server6 smtp accept dst 2001:DB8:2::/64
server6 smtp accept src not 2001:DB8:1::/64 dst 2001:DB8:2::/64
```

When attempting to create rules for both IPv4 and IPv6 it is generally easier to use the src4, src6, dst4 and dst6 pairs:

```
server46 smtp accept src4 192.0.2.1 src6 2001:DB8:1::/64
server46 smtp accept dst4 198.51.100.1 dst6 2001:DB8:2::/64
server46 smtp accept dst4 $d4 dst6 $d6 src4 not $d4 src6 not $s6
```

To keep the rules sane, if one of the 4/6 pair specifies not, then so must the other. If you do not want to use both IPv4 and IPv6 addresses, you must specify the rule as IPv4 or IPv6 only. It is always possible to write a second IPv4 or IPv6 only rule.

### srctype, dsttype
Use srctype or dsttype to define the source or destination IP address type of the request. type is the address type category as used in the kernel's network stack. It can be one of:

UNSPEC

an unspecified address (i.e. 0.0.0.0)

UNICAST

a unicast address

LOCAL

a local address

BROADCAST

a broadcast address

ANYCAST

an anycast address

MULTICAST

a multicast address

BLACKHOLE

a blackhole address

UNREACHABLE

an unreachable address

PROHIBIT

a prohibited address

THROW; NAT; XRESOLVE

undocumented

See iptables(8) or run iptables -m addrtype --help for more information. Examples:

```
server smtp accept srctype not "UNREACHABLE PROHIBIT"

```

### proto
Use proto to match by protocol. The protocol can be any accepted by iptables(8).

### mac
Use mac to match by MAC address. The macaddr matches to the "remote" host. In an interface, "remote" always means the non-local host. In a router, "remote" refers to the source of requests for servers. It refers to the destination of requests for clients. Examples:

```
 # Only allow pop3 requests to the e6 host
 client pop3 accept mac 00:01:01:00:00:e6
 # Only allow hosts other than e7/e8 to access smtp
 server smtp accept mac not "00:01:01:00:00:e7 00:01:01:00:00:e8"
```

### dscp
Use dscp to match the DSCP field on packets. For details on DSCP values and classids, see firehol-dscp(5).

```
 server smtp accept dscp not "0x20 0x30"
 server smtp accept dscp not class "BE EF"
```

### mark
Use mark to match marks set on packets. For details on mark ids, see firehol-mark(5).

```
server smtp accept mark not "20 55"

```

### tos
Use tos to match the TOS field on packets. For details on TOS ids, see firehol-tos(5).

```
server smtp accept tos not "Maximize-Throughput 0x10"

```

### custom
Use custom to pass arguments directly to iptables(8). All of the parameters must be in a single quoted string. To pass an option to iptables(8) that itself contains a space you need to quote strings in the usual bash(1) manner. For example:

```
server smtp accept custom "--some-option some-value"
server smtp accept custom "--some-option 'some-value second-value'"
```

## ROUTER ONLY

### inface, outface
Use inface and outface to define the interface via which a request is received and forwarded respectively. Use the same format as firehol-interface(5). Examples:

```
server smtp accept inface not eth0
server smtp accept inface not "eth0 eth1"
server smtp accept inface eth0 outface eth1
```

### physin, physout
Use physin and physout to define the physical interface via which a request is received or send in cases where the inface or outface is known to be a virtual interface; e.g. a bridge. Use the same format as firehol-interface(5). Examples:

```
server smtp accept physin not eth0

```

## INTERFACE ONLY
These parameters match information related to information gathered from the local host. They apply only to outgoing packets and are silently ignored for incoming requests and requests that will be forwarded.

Note

The Linux kernel infrastructure to match PID/SID and executable names with pid, sid and cmd has been removed so these options can no longer be used.

### uid
Use uid to match the operating system user sending the traffic. The user is a username, uid number or a quoted list of the two.

For example, to limit which users can access POP3 and IMAP by preventing replies for certain users from being sent:

```
client "pop3 imap" accept user not "user1 user2 user3"

```

Similarly, this will allow all requests to reach the server but prevent replies unless the web server is running as apache:

```
server http accept user apache

```

### gid
Use gid to match the operating system group sending the traffic. The group is a group name, gid number or a quoted list of the two.

## LOGGING

### connlog
Use connlog to log only the first packet of a connection.

### log, loglimit
Use log or loglimit to log matching packets to syslog. Unlike iptables(8) logging, this is not an action: FireHOL will produce multiple iptables(8) commands to accomplish both the action for the rule and the logging.

Logging is controlled using the FIREHOL_LOG_OPTIONS and FIREHOL_LOG_LEVEL environment variables - see firehol-defaults.conf(5). loglimit additionally honours the FIREHOL_LOG_FREQUENCY and FIREHOL_LOG_BURST variables.

Specifying level (which takes the same values as FIREHOL_LOG_LEVEL) allows you to override the log level for a single rule.

## HELPERS ONLY PARAMETERS

### dport, sport
FireHOL also provides dport, sport and limit which are used internally and rarely needed within configuration files.

dport and sport require an argument port which can be a name, number, range (FROM:TO) or a quoted list of ports.

For dport port specifies the destination port of a request and can be useful when matching traffic to helper commands (such as nat) where there is no implicit port.

For sport port specifies the source port of a request and can be useful when matching traffic to helper commands (such as nat) where there is no implicit port.

### limit
limit requires the arguments frequency and burst and will limit the matching of traffic in both directions.

### connlimit
connlimit matches on the number of connections per IP. It has been added to FireHOL since v3.

saddr matches on source IP. daddr matches on destination IP. mask groups IPs with the mask given upto matches when the number of connections is up to the given limit above matches when the number of connections above to the given limit

The number of connections counted are system wide, not service specific. For example for saddr, you cannot connlimit 2 connections for SSH and 4 for SMTP. If you connlimit 2 connections for SSH, then the first 2 connections of a client can be SSH. If a client has already 2 connections to another service, the client will not be able to connect to SSH.

So, connlimit can safely be used:

•

with daddr to limit the connections a server can accept

•

with saddr to limit the total connections per client to all services.

### hashlimit
hashlimit has been added to FireHOL since v3.

hashlimit hashlimit uses hash buckets to express a rate limiting match (like the limit match) for a group of connections using a single iptables rule. Grouping can be done per-hostgroup (source and/or destination address) and/or per-port. It gives you the ability to express "N packets per time quantum per group" or "N bytes per seconds" (see below for some examples).

A hash limit type (upto, above) and name are required.

name The name for the /proc/net/ipt_hashlimit/name entry.

upto amount[/second|/minute|/hour|/day] Match if the rate is below or equal to amount/quantum. It is specified either as a number, with an optional time quantum suffix (the default is 3/hour), or as amountb/second (number of bytes per second).

above amount[/second|/minute|/hour|/day] Match if the rate is above amount/quantum.

burst amount Maximum initial number of packets to match: this number gets recharged by one every time the limit specified above is not reached, up to this number; the default is 5. When byte-based rate matching is requested, this option specifies the amount of bytes that can exceed the given rate. This option should be used with caution - if the entry expires, the burst value is reset too.

mode {srcip|srcport|dstip|dstport},... A comma-separated list of objects to take into consideration. If no mode option is given, srcip,dstport is assumed.

srcmask prefix When --hashlimit-mode srcip is used, all source addresses encountered will be grouped according to the given prefix length and the so-created subnet will be subject to hashlimit. prefix must be between (inclusive) 0 and 32. Note that srcmask 0 is basically doing the same thing as not specifying srcip for mode, but is technically more expensive.

dstmask prefix Like srcmask, but for destination addresses.

htable-size buckets The number of buckets of the hash table

htable-max entries Maximum entries in the hash.

htable-expire msec After how many milliseconds do hash entries expire.

htable-gcinterval msec How many milliseconds between garbage collection intervals.

Examples:

matching on source host: "1000 packets per second for every host in 192.168.0.0/16"

```
src 192.168.0.0/16 hashlimit mylimit mode srcip upto 1000/sec
```

matching on source port: "100 packets per second for every service of 192.168.1.1"

```
src 192.168.1.1 hashlimit mylimit mode srcport upto 100/sec
```

matching on subnet: "10000 packets per minute for every /28 subnet (groups of 8 addresses) in 10.0.0.0/8"

```
src 10.0.0.8 hashlimit mylimit mask 28 upto 10000/min
```

matching bytes per second: "flows exceeding 512kbyte/s"

```
hashlimit mylimit mode srcip,dstip,srcport,dstport above 512kb/s
```

matching bytes per second: "hosts that exceed 512kbyte/s, but permit up to 1Megabytes without matching"

```
hashlimit mylimit mode dstip above 512kb/s burst 1mb
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-server(5) - server, route commands

•

firehol-client(5) - client command

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-mark(5) - mark config helper

•

firehol-tos(5) - tos config helper

•

firehol-dscp(5) - dscp config helper

•

firehol-defaults.conf(5) - control variables

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-policy

title: firehol-policy(5)

text:
# firehol-policy(5)

## NAME
firehol-policy - set default action for an interface or router

## SYNOPSIS
policy action

## DESCRIPTION
The policy subcommand defines the default policy for an interface or router.

The action can be any of the actions listed in firehol-actions(5).

Note

Change the default policy of a router only if you understand clearly what will be matched by the router statement whose policy is being changed.

It is common to define overlapping router definitions. Changing the policy to anything other than the default return may cause strange results for your configuration.

Warning

Do not set a policy to accept unless you fully trust all hosts that can reach the interface. FireHOL CANNOT be used to create valid "accept by default" firewalls.

## EXAMPLE

```
interface eth0 intranet src 192.0.2.0/24
  # I trust this interface absolutely
  policy accept
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-protection

title: firehol-protection(5)

summary: add extra protections to a definition

text:
# firehol-protection(5)

## NAME
firehol-protection - add extra protections to a definition

## SYNOPSIS
protection [reverse] strong [requests/period [burst]]

protection [reverse] flood-protection-type [requests/period [burst]]

protection [reverse] { bad-packets | packet-protection-type }

protection [reverse] connlimit connections [mask prefix]

protection [reverse] connrate rate [burst amount] [srcmask prefix] [htable-size buckets] [htable-max entries] [htable-expire msec] [htable-gcinterval msec]

## DESCRIPTION
The protection subcommand sets protection rules on an interface or router.

Flood protections honour the values requests/period and burst. They are used to limit the rate of certain types of traffic.

The default rate FireHOL uses is 100 operations per second with a burst of 50. Run iptables -m limit --help for more information.

The protection type strong will switch on all protections (both packet and flood protections) except all-floods. It has aliases full and all.

The protection type bad-packets will switch on all packet protections but not flood protections.

You can specify multiple protection types by using multiple protection commands or by using a single command and enclosing the types in quotes.

Note

On a router, protections are normally set up on inface.

The reverse option will set up the protections on outface. You must use it as the first keyword.

## PACKET PROTECTION TYPES
bad-packets:

Drops all the bad packets detected by these rules.

invalid

Drops all incoming invalid packets, as detected INVALID by the connection tracker.

See also FIREHOL_DROP_INVALID in firehol-defaults.conf(5) which allows setting this function globally.

fragments

Drops all packet fragments.

This rule will probably never match anything since iptables(8) reconstructs all packets automatically before the firewall rules are processed whenever connection tracking is running.

new-tcp-w/o-syn

Drops all TCP packets that initiate a socket but have not got the SYN flag set.

malformed-xmas

Drops all TCP packets that have all TCP flags set.

malformed-null

Drops all TCP packets that have all TCP flags unset.

malformed-bad

Drops all TCP packets that have illegal combinations of TCP flags set.

### EXAMPLES

```
protection bad-packets
```

## FLOOD PROTECTION TYPES
icmp-floods [requests/period [burst]]

Allows only a certain amount of ICMP echo requests.

syn-floods [requests/period [burst]]

Allows only a certain amount of new TCP connections.

Be careful to not set the rate too low as the rule is applied to all connections regardless of their final result (rejected, dropped, established, etc).

all-floods [requests/period [burst]]

Allows only a certain amount of new connections.

Be careful to not set the rate too low as the rule is applied to all connections regardless of their final result (rejected, dropped, established, etc).

### EXAMPLES

```
protection all-floods 90/sec 40
```

## CLIENT LIMITING TYPES
These protections were added in v3.

These protections are used to limit the connections client make, per interface or router.

They support appending optional rule parameters to limit their scope to certain clients only.

protection [reverse] connlimit connections [mask prefix]

Allow only a number of connections per client (implemented with connlimit with fixed type=saddr).

protection [reverse] connrate rate [burst amount] [srcmask prefix] [htable-size buckets] [htable-max entries] [htable-expire msec] [htable-gcinterval msec]

Allow up to a rate of new connections per client (implemented with hashlimit with fixed type=upto and mode=srcip).

### EXAMPLES
Limit the number of concurrent connections to 10 per client

```
protection connlimit 10 mask 32
```

Limit the number of concurrent connections to 100 per client class-C and also limit it to 5 for 1.2.3.4

```
protection connlimit 100 mask 24
protection connlimit 5 src 1.2.3.4
```

In the last example above, if you want to give client 1.2.3.4 more connections than all others, you should exclude it from the first connlimit statement, like this:

```
protection connlimit 100 mask 24 src not 1.2.3.4
protection connlimit 200 src 1.2.3.4
```

Limit all clients to 10 concurrect connections and 60 connections/minute

```
protection connlimit 10
protection connrate 60/minute
```

## KNOWN ISSUES
When using multiple types in a single command, if the quotes are forgotten, incorrect rules will be generated without warning.

When using multiple types in a single command, FireHOL will silently ignore any types that come after a group type (bad-packets, strong and its aliases). Only use group types on their own line.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-proxy

title: firehol-proxy(5)

summary: create a router definition

text:
# firehol-proxy(5)

## NAME
firehol-router - create a router definition

## SYNOPSIS
{ router | router46 } name rule-params

router4 name rule-params

router6 name rule-params

## DESCRIPTION
A router definition consists of a set of rules for traffic passing through the host running the firewall.

The default policy for router definitions is RETURN, meaning packets are not dropped by any particular router. Packets not matched by any router are dropped at the end of the firewall.

The behaviour of the defined router is controlled by adding subcommands from those listed in ROUTER SUBCOMMANDS.

Note

Writing router4 is equivalent to writing ipv4 router and ensures the defined router is created only in the IPv4 firewall along with any rules within it.

Writing router6 is equivalent to writing ipv6 router and ensures the defined router is created only in the IPv6 firewall along with any rules within it.

Writing router46 is equivalent to writing both router and ensures the defined router is created in both the IPv4 and IPv6 firewalls. Any rules within it will also be applied to both, unless they specify otherwise.

## PARAMETERS
name

This is a name for this router. You should use short names (10 characters maximum) without spaces or other symbols.

A name should be unique for all FireHOL interface and router definitions.

rule-params

The set of rule parameters to further restrict the traffic that is matched to this router.

See firehol-params(5) for information on the parameters that can be used. Some examples:

```
router mylan inface ppp+ outface eth0 src not ${UNROUTABLE_IPS}
router myrouter
```

See firehol.conf(5) for an explanation of ${UNROUTABLE_IPS}.

## WORKING WITH ROUTERS
Routers create stateful iptables(8) rules which match traffic in both directions.

To match some client or server traffic, the input/output interface or source/destination of the request must be specified. All inface/outface and src/dst firehol-params(5) can be given on the router statement (in which case they will be applied to all subcommands for the router) or just within the subcommands of the router.

For example, to define a router which matches requests from any PPP interface and destined for eth0, and on this allowing HTTP servers (on eth0) to be accessed by clients (from PPP) and SMTP clients (from eth0) to access any servers (on PPP):

```
router mylan inface ppp+ outface eth0
  server http accept
  client smtp accept
```

Note

The client subcommand reverses any optional rule parameters passed to the router, in this case the inface and outface.

Equivalently, to define a router which matches all forwarded traffic and within the the router allow HTTP servers on eth0 to be accessible to PPP and any SMTP servers on PPP to be accessible from eth0:

```
router mylan
  server http accept inface ppp+ outface eth0
  server smtp accept inface eth0 outface ppp
```

Note

In this instance two server subcommands are used since there are no parameters on the router to reverse. Avoid the use of the client subcommand in routers unless the inputs and outputs are defined as part of the router.

Any number of routers can be defined and the traffic they match can overlap. Since the default policy is RETURN, any traffic that is not matched by any rules in one will proceed to the next, in order, until none are left.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

firehol-modifiers(5) - ipv4/ipv6 selection

•

firehol-interface(5) - interface definition

•

firehol-iptables(5) - iptables helper

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

### Router Subcommands
•

firehol-policy(5) - policy command

•

firehol-protection(5) - protection command

•

firehol-server(5) - server, route commands

•

firehol-client(5) - client command

•

firehol-group(5) - group command

•

firehol-tcpmss(5) - tcpmss helper

## AUTHORS
FireHOL Team.