# Reference
<!-- DO NOT EDIT: This document was generated by Puppet Strings -->

## 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::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`

##### `manage_initfile`

Data type: `Boolean`

Disable/Enable the management of the ferm init script for RedHat-based OS

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,
}
```

##### create a custom chain, e.g. for managing custom FORWARD chain rule for OpenVPN using custom ferm DSL.

```puppet
$my_rules = @(EOT)
chain OPENVPN_FORWORD_RULES {
  proto udp {
    interface tun0 {
      outerface enp4s0 {
        mod conntrack ctstate (NEW) saddr @ipfilter((10.8.0.0/24)) ACCEPT;
      }
    }
  }
}
| EOT

ferm::chain{'OPENVPN_FORWORD_RULES':
  chain   => 'OPENVPN_FORWORD_RULES',
  content => $my_rules,
}

ferm::rule { "OpenVPN - FORWORD all udp traffic from network 10.8.0.0/24 to subchain OPENVPN_FORWORD_RULES":
  chain     => 'FORWARD',
  action    => 'OPENVPN_FORWORD_RULES',
  saddr     => '10.8.0.0/24',
  proto     => 'udp',
}
```

#### 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]`

Can only be used for custom chains. It allows you to provide your own ferm rules for this chain. Sets the contents of this custom chain to provided value.

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[Variant[Stdlib::Port,String[1]]]`

The destination port, can be a range as string or a single port number as integer

Default value: `undef`

##### `sport`

Data type: `Optional[Variant[Stdlib::Port,String[1]]]`

The source port, can be a range as string or a single port number as integer

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