Firewall Rule Definitions¶
Firewall configuration in debops.ferm
is done through a flexible
definition of rules. There are a number of variables which are used to
reference a set of default rules and can be extended by user defined
rules. Here a description of the involved configurations should be given
so that everyone can customize the ruleset according to individual
requirements.
Default rules¶
By default debops.ferm
configures a number of rules as soon as a
host is part of the [debops_all_hosts]
Ansible host group. The rules
created by default are defined in defaults/main.yml
and activated by
being listed in ferm__default_rules
. They consist of basic rules for
setting the iptables default policies, restricting extensive connection
attempts, logging and more.
In case a firewall is not required or preferred this behaviour can be
disabled by setting ferm__enabled
to False
in the inventory.
Custom rules¶
A custom rule can be enabled by adding a rule definition to one of the
predefined rule lists (ferm__rules
, ferm__group_rules
,
ferm__host_rules
or ferm__dependent_rules
) in the Ansible
inventory. Each rule has to be defined as a YAML dict using some of
the following keys:
domain
- Optional. iptables domain used for the firewall rule. Possible values:
ip,
ip6
. Defaults toferm__domains
. table
- Optional. iptables table to which the rule is added or from which it
is removed. Defaults to
filter
. chain
- Optional. iptables chain to which the rule is added or from which it
is removed. Defaults to
INPUT
. by_role
- Optional. Name of the Ansible role in the format
ROLE_OWNER.ROLE_NAME
which is responsable for the rule. This will be included as a comment in the generated rule file.
Depending on the chosen type, many additional variables are supported. Please check the individual rule type description below.
Rule types¶
There exist a number of predefined rule types for generating firewall rules through ferm. Following a list of the available rule types which can be used to create custom rules.
The 'accept' type¶
This rule type can be used to create rules that match interfaces, ports, remote IP addresses/subnets and can accept the packets, reject, or redirect to a different chain. The following type-specific YAML keys are supported:
accept_any
- Optional. Match all source addresses by default. Possible values:
True
orFalse
. Defaults toTrue
. If this option is set toFalse
anditem.target
is set toREJECT
all traffic is blocked by default. As soon asitem.saddr
is not empty, this configuration doesn't matter anymore. daddr
- Optional. List of destination IP addresses or networks to which the rule is applied.
dport
- Optional. List of destination ports to which the rule is applied.
include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
interface
- Optional. List of network interfaces for incoming packets to which the rule is applied.
interface_present
- Optional. Same as
item.interface
but first check if specified network interfaces exists before adding the firewall rules. multiport
- Optional. Use
iptables multiport
extension. Possible values:True
orFalse
. Defaults toFalse
. outerface
- Optional. List of network interfaces for outgoing packets to which the rule is applied.
outerface_present
- Optional. Same as
item.outerface
but first check if specified network interface exists before adding the firewall rule. protocol
- Optional. Network protocol to which the rule is applied.
protocol_syn
- Optional. Match TCP packet with only the SYN flag set. Possible values
True
orFalse
. If set toFalse
it will match all other packets except the ones with only the SYN flag set. Defaults to unset. realgoto
- Optional. After packet match jump to custom chain. See ferm realgoto for more details.
reject_with
- Optional. Define reject message being sent when the rule
item.target
is set toREJECT
. Defaults toicmp-admin-prohibited
. saddr
- Optional. List of source IP addresses or networks to which this rule is applied.
sport
- Optional. List of source ports to which the rule is applied.
state
- Optional. Connection state which should be matched. Possible values:
INVALID
,ESTABLISHED
,NEW
,RELATED
,UNTRACKED
or comma-separated combination thereof. subchain
- Optional. Subchain name. If more than 3 addresses are listed in
target.saddr
move resulting iptables rules into a separate subchain with the given name. See ferm subchain for more details. target
- Optional. iptables jump target. Possible values:
ACCEPT
,DROP
,REJECT
,RETURN
,NOP
or a custom target. Defaults toACCEPT
.
The 'ansible_controller' type¶
Similar to the accept
type but defaults to the SSH target port and sets the
source address to the host running Ansible if not overwritten through the
item.ansible_controllers
key. The following type-specific YAML keys are
supported:
ansible_controllers
- Optional. List of source IP address which are added to
item.saddr
. Overwrites auto-detection of the Ansible controller address. daddr
- Optional. List of destination IP addresses or networks to which the rule is applied.
dport
- Optional. List of destination ports to which the rule is applied. Defaults to ssh.
include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
interface
- Optional. List of network interfaces for incoming packets to which the rule is applied.
multiport
- Optional. Use iptables multiport extension. Possible values:
True
orFalse
. Defaults toFalse
. outerface
- Optional. List of network interfaces for outgoing packets to which the rule is applied.
protocol
- Optional. Network protocol to which the rule is applied. Defaults to
tcp
. protocol_syn
- Optional. Match TCP packet with only the SYN flag set. Possible values
True
orFalse
. If set toFalse
it will match all other packets except the ones with only the SYN flag set. Defaults to unset. realgoto
- Optional. After packet match jump to custom chain. See ferm realgoto for more details.
reject_with
- Optional. Define reject message being sent when the rule
item.target
is set toREJECT
. Defaults toicmp-admin-prohibited
. saddr
- Optional. List of source IP addresses or networks to which this rule is applied.
sport
- Optional. List of source ports to which the rule is applied.
state
- Optional. Connection state which should be matched. Possible values:
INVALID
,ESTABLISHED
,NEW
,RELATED
,UNTRACKED
or comma-separated combination thereof. subchain
- Optional. Subchain name. If more than 3 addresses are listed in
target.saddr
move resulting iptables rules into a separate subchain with the given name. See ferm subchain for more details. target
- Optional. iptables jump target. Possible values:
ACCEPT
,DROP
,REJECT
,RETURN
,NOP
or a custom target. Defaults toACCEPT
.
The 'connection_tracking' type¶
This type is used to enable connection tracking using the iptables conntrack or iptables state extension. The following type-specific YAML keys are supported:
tracking_active_target
- Optional. iptables jump target for valid connections. Defaults to
ACCEPT
. tracking_invalid_target
- Optional. iptables jump target for invalid connections. Defaults to
DROP
. tracking_module
- Optional. iptables module used for connection tracking. Possible values:
state
orconntrack
. Defaults toconntrack
. interface
- Optional. List of network interfaces for incoming packets to which the rule is applied.
outerface
- Optional. List of network interfaces for outgoing packets to which the rule is applied.
interface_not
- Optional. List of network interfaces for incoming packets which are excluded from the rule.
outerface_not
- Optional. List of network interfaces for outgoing packets which are excluded from the rule.
The 'custom' type¶
The type used to define custom ferm rules. The following additional YAML keys are supported:
rules
- ferm rule definition, required.
by_role
- Optional. Add comment to generated ferm rule definition file that rule is defined in the given Ansible role.
This template is used among others in a debops.libvirtd custom ferm rule.
The 'default_policy' type¶
This type is used to define iptables default policies. The following type-specific YAML keys are supported:
policy
- iptables chain policy, required.
The 'dmz' type¶
This type can be used to enable connection forwarding to another host. If
item.port
is not specified, all traffic is forwarded. The following
type-specific YAML keys are supported:
multiport
- Optional. Use iptables multiport extension. Possible values:
True
orFalse
. Defaults toFalse
. interface
- Optional. List of public network interfaces which accept connections.
At least one of
interface
orpublic_ip
is required. public_ip
- Optional. IPv4 address on the public network which accepts connections.
At least one of
interface
orpublic_ip
is required. Only 1 IP address should be used at a time. private_ip
- IPv4 address of the host on the internal network, required. Only 1 IP address should be used at a time.
protocol(s)
- Optional. List of protocols to forward. Defaults to
tcp
. port(s)
- Optional. List of ports to forward.
dport
- Optional. Destination port to forward to. Only needs to be specified if internal destination port is different from the original destination port.
snat_ip
- Optional. IP address for source address translation. If set the source IP is
rewritten to this address. This is typically the IP address of the firewall
host on the internal network. This is useful if traffic from the
private_ip
would otherwise not be routed back to the firewall host.
The 'hashlimit' type¶
This type is used to define rate limit rules using the iptables hashlimit extension. The following type-specific YAML keys are supported:
daddr
- Optional. List of destination IP addresses or networks to which the rule is applied.
dport
- Optional. List of destination ports to which the rule is applied.
hashlimit_burst
- Optional. Number of packets to match within the expiration time. Defaults
to
5
. hashlimit_expire
- Optional. Expiration time of hash entries in seconds. Defaults to
1.8
. hashlimit_target
- Optional. Jump target used when packet matches the
hashlimit
rule which means that the rate limit is not reached yet. Defaults toRETURN
. hashlimit_mode
- Optional. Options to take into consideration when associating packet
streams. Possible values:
srcip
,srcport
,dstip
,dstport
or a comma-separated list thereof. Defaults tosrcip
. interface
- Optional. List of network interfaces for incoming packets to which the rule is applied.
interface_present
- Optional. Same as
item.interface
but first check if specified network interfaces exists before adding the firewall rules. outerface
- Optional. List of network interfaces for outgoing packets to which the rule is applied.
outerface_present
- Optional. Same as
item.outerface
but first check if specified network interface exists before adding the firewall rule. include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
log
- Optional. Write rate limit hits to syslog. Possible values:
True
andFalse
. Defaults toTrue
. protocol
- Optional. Network protocol to which the rule is applied.
protocol_syn
- Optional. Match TCP packet with only the SYN flag set. Possible values
True
orFalse
. If set toFalse
it will match all other packets except the ones with only the SYN flag set. Defaults to unset. reject_with
- Optional. Define reject message being sent when the rule
item.target
is set toREJECT
. Defaults toicmp-admin-prohibited
. state
- Optional. Connection state which should be matched. Possible values:
INVALID
,ESTABLISHED
,NEW
,RELATED
,UNTRACKED
or comma-separated combination thereof. subchain
- Optional. Subchain name. Move resulting iptables rules into a separate subchain with the given name. See ferm subchain for more details.
target
- Optional. iptables jump target in case the rate limit is reached.
Defaults to
REJECT
.
The 'include' type¶
This type can be used to include custom ferm configuration files. The following type-specific YAML keys are supported:
include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
The 'log' type¶
This type can be used to specify logging rules using the iptables log extension. The following type-specific YAML keys are supported:
include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
log_burst
- Optional. Burst limit of packets being logged. Defaults to
ferm__log_burst
. log_ip_options
- Optional. Log IP options of packet. Possible values:
True
orFalse
. Defaults toTrue
. log_level
- Optional. Log level for firewall messages. Possible values are:
emerg
,alert
,crit
,error
,warning
,notice
,info
ordebug
. Defaults towarning
. log_limit
- Optional. Rate limit of packets being logged. Defaults to
ferm__log_limit
. log_prefix
- Optional. Prefix (up to 29 characters) for firewall log messages. Defaults to iptables-log:
log_target
- Optional. Select how iptables performs logging. Possible values:
LOG
,ULOG
,NFLOG
. Defaults toLOG
. log_tcp_options
- Optional. Log TCP options of packet. Possible values:
True
orFalse
. Defaults toFalse
. log_tcp_sequence
- Optional. Log TCP sequence of packet. Possible values:
True
orFalse
. Defaults toFalse
. realgoto
- Optional. After packet match jump to custom chain. See ferm realgoto for more details.
reject_with
- Optional. Define reject message being sent when the rule
item.target
is set toREJECT
. Defaults toicmp-admin-prohibited
. target
- Optional. iptables jump target for logged packets.
The 'recent' type¶
This type can be used to track connections and respond accordingly by using the iptables recent extension. The following type-specific YAML keys are supported:
dport
- Optional. List of destination ports to which the rule is applied.
include
- Optional. Custom ferm configuration file to include. See ferm include for more details.
multiport
- Optional. Use iptables multiport extension. Possible values:
True
orFalse
. Defaults toFalse
. protocol
- Optional. Network protocol to which the rule is applied.
protocol_syn
- Optional. Match TCP packet with only the SYN flag set. Possible values
True
orFalse
. If set toFalse
it will match all other packets except the ones with only the SYN flag set. Defaults to unset. recent_hitcount
- Optional. Must be used in combination with
item.recent_update
. Match if address is in the list and at least the given number of packets were received so far. recent_log
- Optional. Log packets matching the rule. Possible values:
True
orFalse
. Defaults toferm__log
. If this is set toTrue
ferm__log
must be enabled too for the packet to be logged. recent_name
- Optional. Name of the list. Defaults to
DEFAULT
. recent_remove
- Optional. Remove address from the list. Possible values:
True
orFalse
. Defaults toFalse
. Mutually exclusive withitem.recent_update
. recent_seconds
- Optional. Must be used in combination with
item.recent_update
. Match if address is in the list and was last seen within the given number of seconds. recent_set_name
- Optional. Add the source address of a matching packet to the given list. This
must correspond with
item.recent_name
of a second rule which would potentially act on the packet, e. g. reject it. recent_target
- Optional. iptables jump target when packet has hit the recent list.
Possible values:
ACCEPT
,DROP
,REJECT
,RETURN
,NOP
or a custom target. Defaults toNOP
. recent_update
- Optional. Update "last-seen" timestamp. Possible values:
True
orFalse
. Defaults toFalse
. Mutually exclusive withitem.recent_remove
. reject_with
- Optional. Define reject message being sent when the rule
item.target
is set toREJECT
. Defaults toicmp-admin-prohibited
. state
- Optional. Connection state which should be matched. Possible values:
INVALID
,ESTABLISHED
,NEW
,RELATED
,UNTRACKED
or comma-separated combination thereof. subchain
- Optional. Subchain name. Move resulting iptables rules into a separate subchain with the name given. See ferm subchain for more details.
When using the recent
type make sure to always define two
rules:
- One for matching the packet against the address list using the
item.recent_update
feature. If this filter matches you likely want to set theitem.recent_target
toDROP
orREJECT
. - To clear the source address from the list again in case the connection
restrictions are not met, add a second role using
item.recent_remove
.
The 'reject' type¶
This type is used to reject all traffic. It can be added for example as a final rule in a custom chain.
Legacy rules¶
Legacy rules are the (old) deprecated way to configure firewall rules using a simpler less flexible syntax than described above. As support for these is likely going to be removed in the future, they shouldn't be used anymore.
Support for legacy rules is still enabled by default. However, they are
stored in a separate iptables INPUT chain called
debops-legacy-input-rules
. In case you haven't defined any legacy
rules and none of the DebOps roles you are using are still depending
on it, disable support completely by setting ferm__include_legacy
to False
which will avoid the additional chain from being created.
If you're not sure if you still have legacy rules defined, look for
variable names with only on '_' after the ferm prefix (e. g.
ferm_input_list
and ferm_input_dependent_list
).