Reference
Table of Contents
Classes
Public Classes
ferm
: This class manages ferm installation and rule generation on modern linux systems
Private Classes
ferm::config
: This class handles the configuration file. Avoid modifying private classes.ferm::install
: This class handles the configuration file. Avoid modifying private classes.ferm::service
: This class handles the configuration file. Avoid modifying private classes.
Defined types
ferm::chain
: This defined resource manages ferm/iptables chainsferm::ipset
: a defined resource that can match for ipsets at the top of a chain. This is a per-chain resource. You cannot mix IPv4 and IPv6 sets.ferm::rule
: This defined resource manages a single rule in a specific chain
Data types
Ferm::Actions
: a list of allowed actions for a ruleFerm::Policies
: a list of allowed policies for a chainFerm::Port
: ferm port-specFerm::Protocols
: a list of allowed protocolls to matchFerm::Tables
: a list of available tables
Classes
ferm
This class manages ferm installation and rule generation on modern linux systems
Examples
deploy ferm without any configured rules, but also don't start the service or modify existing config files
include ferm
deploy ferm and start it, on nodes with only ipv6 enabled
class{'ferm':
manage_service => true,
ip_versions => ['ip6'],
}
deploy ferm and don't touch chains from other software, like fail2ban and docker
class{'ferm':
manage_service => true,
preserve_chains_in_tables => {
'filter' => [
'f2b-sshd',
'DOCKER',
'DOCKER-ISOLATION-STAGE-1',
'DOCKER-ISOLATION-STAGE-2',
'DOCKER-USER',
'FORWARD',
],
'nat' => [
'DOCKER',
],
},
}
Parameters
The following parameters are available in the ferm
class:
manage_service
manage_configfile
configfile
configdirectory
forward_disable_conntrack
output_disable_conntrack
input_disable_conntrack
forward_policy
output_policy
input_policy
input_drop_invalid_packets_with_conntrack
rules
chains
forward_log_dropped_packets
output_log_dropped_packets
input_log_dropped_packets
ip_versions
preserve_chains_in_tables
install_method
package_ensure
vcsrepo
vcstag
manage_service
Data type: Boolean
Disable/Enable the management of the ferm daemon
Default value: false
manage_configfile
Data type: Boolean
Disable/Enable the management of the ferm default config
Default value: false
configfile
Data type: Stdlib::Absolutepath
Path to the config file
configdirectory
Data type: Stdlib::Absolutepath
Path to the directory where the module stores ferm configuration files
forward_disable_conntrack
Data type: Boolean
Enable/Disable the generation of conntrack rules for the FORWARD chain
Default value: true
output_disable_conntrack
Data type: Boolean
Enable/Disable the generation of conntrack rules for the OUTPUT chain
Default value: true
input_disable_conntrack
Data type: Boolean
Enable/Disable the generation of conntrack rules for the INPUT chain
Default value: false
forward_policy
Data type: Ferm::Policies
Default policy for the FORWARD chain
Default value: 'DROP'
output_policy
Data type: Ferm::Policies
Default policy for the OUTPUT chain
Default value: 'ACCEPT'
input_policy
Data type: Ferm::Policies
Default policy for the INPUT chain
Default value: 'DROP'
input_drop_invalid_packets_with_conntrack
Data type: Boolean
Enable/Disable the mod conntrack ctstate INVALID DROP
statement. Only works if $disable_conntrack
is false
. You can set this to false if your policy is DROP. This only effects the INPUT chain.
Default value: false
rules
Data type: Hash
A hash that holds all data for ferm::rule
Default value: {}
chains
Data type: Hash
A hash that holds all data for ferm::chain
Default value: {}
forward_log_dropped_packets
Data type: Boolean
Enable/Disable logging in the FORWARD chain of packets to the kernel log, if no explicit chain matched
Default value: false
output_log_dropped_packets
Data type: Boolean
Enable/Disable logging in the OUTPUT chain of packets to the kernel log, if no explicit chain matched
Default value: false
input_log_dropped_packets
Data type: Boolean
Enable/Disable logging in the INPUT chain of packets to the kernel log, if no explicit chain matched
Default value: false
ip_versions
Data type: Array[Enum['ip','ip6']]
Set list of versions of ip we want ot use.
Default value: ['ip','ip6']
preserve_chains_in_tables
Data type: Hash[String[1],Array[String[1]]]
Hash with table:chains[] to use ferm @preserve for (since ferm v2.4) Example: {'nat' => ['PREROUTING', 'POSTROUTING']}
Default value: {}
install_method
Data type: Enum['package','vcsrepo']
method used to install ferm
Default value: 'package'
package_ensure
Data type: String[1]
sets the ensure parameter for the package resource
Default value: 'installed'
vcsrepo
Data type: Stdlib::HTTPSUrl
git repository where ferm sources are hosted
Default value: 'https://github.com/MaxKellermann/ferm.git'
vcstag
Data type: String[1]
git tag used when install_method is vcsrepo
Default value: 'v2.5.1'
Defined types
ferm::chain
This defined resource manages ferm/iptables chains
Examples
create a custom chain, e.g. for all incoming SSH connections
ferm::chain{'check-ssh':
chain => 'SSH',
disable_conntrack => true,
log_dropped_packets => true,
}
Parameters
The following parameters are available in the ferm::chain
defined type:
disable_conntrack
drop_invalid_packets_with_conntrack
log_dropped_packets
policy
chain
table
ip_versions
content
disable_conntrack
Data type: Boolean
Disable/Enable usage of conntrack. By default, we enable conntrack only for the filter INPUT chain
Default value: true
drop_invalid_packets_with_conntrack
Data type: Boolean
Enable/Disable the mod conntrack ctstate INVALID DROP
statement. Only works if $disable_conntrack
is false
in this chain. You can set this to false if your policy is DROP.
Default value: false
log_dropped_packets
Data type: Boolean
Enable/Disable logging of packets to the kernel log, if no explicit chain matched
Default value: false
policy
Data type: Optional[Ferm::Policies]
Set the default policy for CHAIN (works only for builtin chains) Allowed values: (ACCEPT|DROP) (see Ferm::Policies type)
Default value: undef
chain
Data type: String[1]
Name of the chain that should be managed Allowed values: String[1]
Default value: $name
table
Data type: Ferm::Tables
Select the target table (filter/raw/mangle/nat) Allowed values: (filter|raw|mangle|nat) (see Ferm::Tables type)
Default value: 'filter'
ip_versions
Data type: Array[Enum['ip', 'ip6']]
Set list of versions of ip we want ot use.
Default value: $ferm::ip_versions
content
Data type: Optional[String[1]]
custom string that will be written into th chain file
Default value: undef
ferm::ipset
a defined resource that can match for ipsets at the top of a chain. This is a per-chain resource. You cannot mix IPv4 and IPv6 sets.
- See also
- http://ferm.foo-projects.org/download/2.1/ferm.html#set
Examples
Create an iptables rule that allows traffic that matches the ipset internet
ferm::ipset { 'CONSUL':
sets => {
'internet' => 'ACCEPT'
},
}
create two matches for IPv6, both at the end of the INPUT
chain. Explicitly mention the filter
table.
ferm::ipset { 'INPUT':
prepend_to_chain => false,
table => 'filter',
ip_version => 'ip6',
sets => {
'testset01' => 'ACCEPT',
'anothertestset' => 'DROP'
},
}
Parameters
The following parameters are available in the ferm::ipset
defined type:
sets
Data type: Hash[String[1], Ferm::Actions]
A hash with multiple sets. For each hash you can provide an action like DROP
or ACCEPT
.
chain
Data type: String[1]
name of the chain we want to apply those rules to. The name of the defined resource will be used as default value for this.
Default value: $name
table
Data type: Ferm::Tables
name of the table where we want to apply this. Defaults to filter
because that's the most common usecase.
Default value: 'filter'
ip_version
Data type: Enum['ip','ip6']
sadly, ip sets are version specific. You cannot mix IPv4 and IPv6 addresses. Because of this you need to provide the version.
Default value: 'ip'
prepend_to_chain
Data type: Boolean
By default, ipset rules are added to the top of the chain. Set this to false to append them to the end instead.
Default value: true
ferm::rule
This defined resource manages a single rule in a specific chain
Examples
Jump to the 'SSH' chain for all incoming SSH traffic (see chain.pp examples on how to create the chain)
ferm::rule{'incoming-ssh':
chain => 'INPUT',
action => 'SSH',
proto => 'tcp',
dport => 22,
}
Create a rule in the 'SSH' chain to allow connections from localhost
ferm::rule{'allow-ssh-localhost':
chain => 'SSH',
action => 'ACCEPT',
proto => 'tcp',
dport => 22,
saddr => '127.0.0.1',
}
Confuse people that do a traceroute/mtr/ping to your system
ferm::rule{'drop-icmp-time-exceeded':
chain => 'OUTPUT',
action => 'DROP',
proto => 'icmp',
proto_options => 'icmp-type time-exceeded',
}
allow multiple protocols
ferm::rule{'allow_consul':
chain => 'INPUT',
action => 'ACCEPT',
proto => ['udp', 'tcp'],
dport => 8301,
}
Parameters
The following parameters are available in the ferm::rule
defined type:
chain
Data type: String[1]
Configure the chain where we want to add the rule
proto
Data type: Ferm::Protocols
Which protocol do we want to match, typically UDP or TCP
comment
Data type: String
A comment that will be added to the ferm config and to ip{,6}tables
Default value: $name
action
Data type: Ferm::Actions
Configure what we want to do with the packet (drop/accept/reject, can also be a target chain name). The parameter is mandatory. Allowed values: (RETURN|ACCEPT|DROP|REJECT|NOTRACK|LOG|MARK|DNAT|SNAT|MASQUERADE|REDIRECT|String[1])
dport
Data type: Optional[Ferm::Port]
The destination port, can be a single port number as integer or an Array of integers (which will then use the multiport matcher)
Default value: undef
sport
Data type: Optional[Ferm::Port]
The source port, can be a single port number as integer or an Array of integers (which will then use the multiport matcher)
Default value: undef
saddr
Data type: Optional[Variant[Array, String[1]]]
The source address we want to match
Default value: undef
daddr
Data type: Optional[Variant[Array, String[1]]]
The destination address we want to match
Default value: undef
proto_options
Data type: Optional[String[1]]
Optional parameters that will be passed to the protocol (for example to match specific ICMP types)
Default value: undef
interface
Data type: Optional[String[1]]
an Optional interface where this rule should be applied
Default value: undef
ensure
Data type: Enum['absent','present']
Set the rule to present or absent
Default value: 'present'
table
Data type: Ferm::Tables
Select the target table (filter/raw/mangle/nat) Default value: filter Allowed values: (filter|raw|mangle|nat) (see Ferm::Tables type)
Default value: 'filter'
Data types
Ferm::Actions
As you can also jump to other chains, each chain-name is also a valid action/target
Alias of
Variant[Enum['RETURN', 'ACCEPT', 'DROP', 'REJECT', 'NOTRACK', 'LOG', 'MARK', 'DNAT', 'SNAT', 'MASQUERADE', 'REDIRECT'], String[1]]
Ferm::Policies
a list of allowed policies for a chain
Alias of
Enum['ACCEPT', 'DROP']
Ferm::Port
allowed variants:
- single Integer port
- Array of Integers (creates a multiport matcher)
- ferm range port-spec (pair of colon-separated integer, assumes 0 if first is omitted)
Alias of
Variant[Stdlib::Port, Array[Stdlib::Port], Pattern['^\d*:\d+$']]
Ferm::Protocols
a list of allowed protocolls to match
Alias of
Variant[Integer[0, 255], Array[Integer[0, 255]], Enum['icmp', 'tcp', 'udp', 'udplite', 'icmpv6', 'esp', 'ah', 'sctp', 'mh', 'all'], Array[Enum['icmp', 'tcp', 'udp', 'udplite', 'icmpv6', 'esp', 'ah', 'sctp', 'mh', 'all']]]
Ferm::Tables
a list of available tables
Alias of
Enum['raw', 'mangle', 'nat', 'filter']