REFERENCE.md

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 chains
• 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.
• ferm::rule: This defined resource manages a single rule in a specific chain

Data types

• Ferm::Actions: a list of allowed actions for a rule
• Ferm::Negation: list of keywords that support negation
• Ferm::Policies: a list of allowed policies for a chain
• Ferm::Port: ferm port-spec
• Ferm::Protocols: a list of allowed protocolls to match
• Ferm::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
• manage_package
• 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

manage_package

Data type: Boolean

Disable/Enable the management of the ferm package

Default value: true

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.6'

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
• chain
• table
• ip_version
• prepend_to_chain

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
• proto
• comment
• action
• dport
• sport
• saddr
• daddr
• proto_options
• interface
• ensure
• table
• negate

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'

negate

Data type: Optional[Ferm::Negation]

Single keyword or array of keywords to negate Default value: undef Allowed values: (saddr|daddr|sport|dport) (see Ferm::Negation type)

Default value: undef

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::Negation

list of keywords that support negation

Alias of Variant[Enum['saddr', 'daddr', 'sport', 'dport'], Array[Enum['saddr', 'daddr', 'sport', 'dport']]]

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']