path: root/REFERENCE.md

# 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::Port`](#fermport): ferm port-spec
* [`Ferm::Protocols`](#fermprotocols): a list of allowed protocolls to match
* [`Ferm::Tables`](#fermtables): a list of available tables

## Classes

### <a name="ferm"></a>`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`](#manage_service)
* [`manage_configfile`](#manage_configfile)
* [`configfile`](#configfile)
* [`configdirectory`](#configdirectory)
* [`forward_disable_conntrack`](#forward_disable_conntrack)
* [`output_disable_conntrack`](#output_disable_conntrack)
* [`input_disable_conntrack`](#input_disable_conntrack)
* [`forward_policy`](#forward_policy)
* [`output_policy`](#output_policy)
* [`input_policy`](#input_policy)
* [`input_drop_invalid_packets_with_conntrack`](#input_drop_invalid_packets_with_conntrack)
* [`rules`](#rules)
* [`chains`](#chains)
* [`forward_log_dropped_packets`](#forward_log_dropped_packets)
* [`output_log_dropped_packets`](#output_log_dropped_packets)
* [`input_log_dropped_packets`](#input_log_dropped_packets)
* [`ip_versions`](#ip_versions)
* [`preserve_chains_in_tables`](#preserve_chains_in_tables)
* [`install_method`](#install_method)
* [`package_ensure`](#package_ensure)
* [`vcsrepo`](#vcsrepo)
* [`vcstag`](#vcstag)

##### <a name="manage_service"></a>`manage_service`

Data type: `Boolean`

Disable/Enable the management of the ferm daemon

Default value: ``false``

##### <a name="manage_configfile"></a>`manage_configfile`

Data type: `Boolean`

Disable/Enable the management of the ferm default config

Default value: ``false``

##### <a name="configfile"></a>`configfile`

Data type: `Stdlib::Absolutepath`

Path to the config file

##### <a name="configdirectory"></a>`configdirectory`

Data type: `Stdlib::Absolutepath`

Path to the directory where the module stores ferm configuration files

##### <a name="forward_disable_conntrack"></a>`forward_disable_conntrack`

Data type: `Boolean`

Enable/Disable the generation of conntrack rules for the FORWARD chain

Default value: ``true``

##### <a name="output_disable_conntrack"></a>`output_disable_conntrack`

Data type: `Boolean`

Enable/Disable the generation of conntrack rules for the OUTPUT chain

Default value: ``true``

##### <a name="input_disable_conntrack"></a>`input_disable_conntrack`

Data type: `Boolean`

Enable/Disable the generation of conntrack rules for the INPUT chain

Default value: ``false``

##### <a name="forward_policy"></a>`forward_policy`

Data type: `Ferm::Policies`

Default policy for the FORWARD chain

Default value: `'DROP'`

##### <a name="output_policy"></a>`output_policy`

Data type: `Ferm::Policies`

Default policy for the OUTPUT chain

Default value: `'ACCEPT'`

##### <a name="input_policy"></a>`input_policy`

Data type: `Ferm::Policies`

Default policy for the INPUT chain

Default value: `'DROP'`

##### <a name="input_drop_invalid_packets_with_conntrack"></a>`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``

##### <a name="rules"></a>`rules`

Data type: `Hash`

A hash that holds all data for ferm::rule

Default value: `{}`

##### <a name="chains"></a>`chains`

Data type: `Hash`

A hash that holds all data for ferm::chain

Default value: `{}`

##### <a name="forward_log_dropped_packets"></a>`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``

##### <a name="output_log_dropped_packets"></a>`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``

##### <a name="input_log_dropped_packets"></a>`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``

##### <a name="ip_versions"></a>`ip_versions`

Data type: `Array[Enum['ip','ip6']]`

Set list of versions of ip we want ot use.

Default value: `['ip','ip6']`

##### <a name="preserve_chains_in_tables"></a>`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: `{}`

##### <a name="install_method"></a>`install_method`

Data type: `Enum['package','vcsrepo']`

method used to install ferm

Default value: `'package'`

##### <a name="package_ensure"></a>`package_ensure`

Data type: `String[1]`

sets the ensure parameter for the package resource

Default value: `'installed'`

##### <a name="vcsrepo"></a>`vcsrepo`

Data type: `Stdlib::HTTPSUrl`

git repository where ferm sources are hosted

Default value: `'https://github.com/MaxKellermann/ferm.git'`

##### <a name="vcstag"></a>`vcstag`

Data type: `String[1]`

git tag used when install_method is vcsrepo

Default value: `'v2.5.1'`

## Defined types

### <a name="fermchain"></a>`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`](#disable_conntrack)
* [`drop_invalid_packets_with_conntrack`](#drop_invalid_packets_with_conntrack)
* [`log_dropped_packets`](#log_dropped_packets)
* [`policy`](#policy)
* [`chain`](#chain)
* [`table`](#table)
* [`ip_versions`](#ip_versions)
* [`content`](#content)

##### <a name="disable_conntrack"></a>`disable_conntrack`

Data type: `Boolean`

Disable/Enable usage of conntrack. By default, we enable conntrack only for the filter INPUT chain

Default value: ``true``

##### <a name="drop_invalid_packets_with_conntrack"></a>`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``

##### <a name="log_dropped_packets"></a>`log_dropped_packets`

Data type: `Boolean`

Enable/Disable logging of packets to the kernel log, if no explicit chain matched

Default value: ``false``

##### <a name="policy"></a>`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``

##### <a name="chain"></a>`chain`

Data type: `String[1]`

Name of the chain that should be managed
Allowed values: String[1]

Default value: `$name`

##### <a name="table"></a>`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'`

##### <a name="ip_versions"></a>`ip_versions`

Data type: `Array[Enum['ip', 'ip6']]`

Set list of versions of ip we want ot use.

Default value: `$ferm::ip_versions`

##### <a name="content"></a>`content`

Data type: `Optional[String[1]]`

custom string that will be written into th chain file

Default value: ``undef``

### <a name="fermipset"></a>`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`](#sets)
* [`chain`](#chain)
* [`table`](#table)
* [`ip_version`](#ip_version)
* [`prepend_to_chain`](#prepend_to_chain)

##### <a name="sets"></a>`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`.

##### <a name="chain"></a>`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`

##### <a name="table"></a>`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'`

##### <a name="ip_version"></a>`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'`

##### <a name="prepend_to_chain"></a>`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``

### <a name="fermrule"></a>`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',
  action        => 'DROP',
  proto         => 'icmp',
  proto_options => 'icmp-type time-exceeded',
}
```

##### allow multiple protocols

```puppet
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`](#chain)
* [`proto`](#proto)
* [`comment`](#comment)
* [`action`](#action)
* [`dport`](#dport)
* [`sport`](#sport)
* [`saddr`](#saddr)
* [`daddr`](#daddr)
* [`proto_options`](#proto_options)
* [`interface`](#interface)
* [`ensure`](#ensure)
* [`table`](#table)

##### <a name="chain"></a>`chain`

Data type: `String[1]`

Configure the chain where we want to add the rule

##### <a name="proto"></a>`proto`

Data type: `Ferm::Protocols`

Which protocol do we want to match, typically UDP or TCP

##### <a name="comment"></a>`comment`

Data type: `String`

A comment that will be added to the ferm config and to ip{,6}tables

Default value: `$name`

##### <a name="action"></a>`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])

##### <a name="dport"></a>`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``

##### <a name="sport"></a>`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``

##### <a name="saddr"></a>`saddr`

Data type: `Optional[Variant[Array, String[1]]]`

The source address we want to match

Default value: ``undef``

##### <a name="daddr"></a>`daddr`

Data type: `Optional[Variant[Array, String[1]]]`

The destination address we want to match

Default value: ``undef``

##### <a name="proto_options"></a>`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``

##### <a name="interface"></a>`interface`

Data type: `Optional[String[1]]`

an Optional interface where this rule should be applied

Default value: ``undef``

##### <a name="ensure"></a>`ensure`

Data type: `Enum['absent','present']`

Set the rule to present or absent

Default value: `'present'`

##### <a name="table"></a>`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

### <a name="fermactions"></a>`Ferm::Actions`

As you can also *jump* to other chains, each chain-name is also a valid action/target

Alias of

```puppet
Variant[Enum['RETURN', 'ACCEPT', 'DROP', 'REJECT', 'NOTRACK', 'LOG', 'MARK', 'DNAT', 'SNAT', 'MASQUERADE', 'REDIRECT'], String[1]]
```

### <a name="fermpolicies"></a>`Ferm::Policies`

a list of allowed policies for a chain

Alias of

```puppet
Enum['ACCEPT', 'DROP']
```

### <a name="fermport"></a>`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

```puppet
Variant[Stdlib::Port, Array[Stdlib::Port], Pattern['^\d*:\d+$']]
```

### <a name="fermprotocols"></a>`Ferm::Protocols`

a list of allowed protocolls to match

Alias of

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

### <a name="fermtables"></a>`Ferm::Tables`

a list of available tables

Alias of

```puppet
Enum['raw', 'mangle', 'nat', 'filter']
```