# Reference ## Table of Contents ### Classes #### Public Classes * [`ferm`](#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`](#fermchain): This defined resource manages ferm/iptables chains * [`ferm::ipset`](#fermipset): 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`](#fermrule): This defined resource manages a single rule in a specific chain ### Data types * [`Ferm::Actions`](#fermactions): a list of allowed actions for a rule * [`Ferm::Policies`](#fermpolicies): a list of allowed policies for a chain * [`Ferm::Port`](#fermport): ferm port-spec * [`Ferm::Protocols`](#fermprotocols): a list of allowed protocolls to match * [`Ferm::Tables`](#fermtables): 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 ```puppet include ferm ``` ##### deploy ferm and start it, on nodes with only ipv6 enabled ```puppet class{'ferm': manage_service => true, ip_versions => ['ip6'], } ``` ##### deploy ferm and don't touch chains from other software, like fail2ban and docker ```puppet 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` 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'` ##### `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 ```puppet 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` 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` ```puppet ferm::ipset { 'CONSUL': sets => { 'internet' => 'ACCEPT' }, } ``` ##### create two matches for IPv6, both at the end of the `INPUT` chain. Explicitly mention the `filter` table. ```puppet 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) ```puppet ferm::rule{'incoming-ssh': chain => 'INPUT', action => 'SSH', proto => 'tcp', dport => 22, } ``` ##### Create a rule in the 'SSH' chain to allow connections from localhost ```puppet 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 ```puppet ferm::rule{'drop-icmp-time-exceeded': chain => 'OUTPUT', policy => 'DROP', proto => 'icmp', proto_options => 'icmp-type time-exceeded', } ``` ##### allow multiple protocols ```puppet ferm::rule{'allow_consul': chain => 'INPUT', policy => '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: `Optional[Ferm::Actions]` Configure what we want to do with the packet (drop/accept/reject, can also be a target chain name) Default value: undef Allowed values: (RETURN|ACCEPT|DROP|REJECT|NOTRACK|LOG|MARK|DNAT|SNAT|MASQUERADE|REDIRECT|String[1]) Default value: ``undef`` ##### `policy` Data type: `Optional[Ferm::Policies]` Configure what we want to do with the packet (drop/accept/reject, can also be a target chain name) [DEPRECATED] Default value: undef Allowed values: (RETURN|ACCEPT|DROP|REJECT|NOTRACK|LOG|MARK|DNAT|SNAT|MASQUERADE|REDIRECT|String[1]) Default value: ``undef`` ##### `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[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']`