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

Class: ferm

#### 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',
    ]
  }
}
```

#### 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
Allowed values: (true|false)

##### `manage_configfile`

Data type: `Boolean`

Disable/Enable the management of the ferm default config
Default value: false
Allowed values: (true|false)

##### `manage_initfile`

Data type: `Boolean`

Disable/Enable the management of the ferm init script for RedHat-based OS
Default value: false
Allowed values: (true|false)

##### `configfile`

Data type: `Stdlib::Absolutepath`

Path to the config file
Default value: /etc/ferm.conf
Allowed values: Stdlib::Absolutepath

##### `configdirectory`

Data type: `Stdlib::Absolutepath`

Path to the directory where the module stores ferm configuration files
Default value: /etc/ferm.d or /etc/ferm/ferm.d
Allowed values: Stdlib::Absolutepath

##### `disable_conntrack`

Data type: `Boolean`

Disable/Enable the generation of conntrack rules
Default value: false
Allowed values: (true|false)

##### `forward_policy`

Data type: `Ferm::Policies`

Default policy for the FORWARD chain
Default value: DROP
Allowed values: (ACCEPT|DROP)

##### `output_policy`

Data type: `Ferm::Policies`

Default policy for the OUTPUT chain
Default value: ACCEPT
Allowed values: (ACCEPT|DROP)

##### `input_policy`

Data type: `Ferm::Policies`

Default policy for the INPUT chain
Default value: DROP
Allowed values: (ACCEPT|DROP)

##### `rules`

Data type: `Hash`

A hash that holds all data for ferm::rule
Default value: Empty Hash
Allowed value: Any Hash

##### `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
Allowed values: (true|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
Allowed values: (true|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
Allowed values: (true|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
Default value: Empty Hash
Allowed values: Hash with a list of tables and chains in it to preserve
Example: {'nat' => ['PREROUTING', 'POSTROUTING']}

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

##### `log_dropped_packets`

Data type: `Boolean`

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

##### `policy`

Data type: `Optional[Ferm::Policies]`

Set the default policy for CHAIN (works only for builtin chains)
Default value: undef
Allowed values: (ACCEPT|DROP) (see Ferm::Policies type)

Default value: `undef`

##### `chain`

Data type: `String[1]`

Name of the chain that should be managed
Default value: $name (resource name)
Allowed values: String[1]

Default value: $name

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

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

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