Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

ferm

deploy and manage ferm
Project URLRSS FeedReport issues

21,268 downloads

156 latest version

4.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 10.0.0 (latest)
  • 9.0.0
  • 8.1.0
  • 8.0.0
  • 7.0.1
  • 7.0.0
  • 6.0.0
  • 5.0.0
  • 4.0.0
  • 3.0.1
  • 3.0.0
  • 2.7.0
  • 2.6.0
  • 2.5.0
  • 2.4.0
  • 2.3.0
  • 2.2.0
  • 2.1.0
  • 2.0.0
  • 1.4.0
  • 1.3.2
  • 1.3.1
  • 1.3.0
  • 1.2.0
  • 1.1.1
released Jun 13th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppet-ferm', '10.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppet-ferm
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppet-ferm --version 10.0.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppet/ferm — version 10.0.0 Jun 13th 2024

puppet-ferm

Build Status Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores Yard Docs AGPL v3 License

Table of Contents

Overview

This module manages the ferm firewalling software. It allows you to configure the actual software, but also all related rules.

What happened to older releases?

You maybe wonder what happend to release 1.1.0 and 1.0.0. We had to take them down because they contained sensitive information.

Setup

This is very easy:

include ferm

This will install the package, but nothing more. It won't explicitly enable it or write any rules. Be careful here: The default Debian package enabled autostart for the service and only allows incoming SSH/IPSec connections.

It is also possible to install ferm from sources:

class {'ferm':
  install_method = 'vcsrepo',
}

When install_method is vcsrepo, the git binary is required, this module should handle Git installation.

When install_method is vcsrepo with vcstag >= v2.5 ferm call "legacy" xtables tools because nft based tools are incompatible.

You can easily define rules in Puppet (they don't need to be exported resources):

  @@ferm::rule{"allow_kafka_server2server-${trusted['certname']}":
    chain  => 'INPUT',
    action => 'ACCEPT',
    proto  => 'tcp',
    dport  => [9092, 9093],
    saddr  => "(${facts['networking']['ip6']}/128 ${facts['networking']['ip']}/32)",
    tag    => 'allow_kafka_server2server',
  }

You can collect them like this:

# collect all exported resources with the tag allow_vault_server2server
Ferm::Rule <<| tag == 'allow_kafka_server2server' |>>

You can also define rules in Hiera. Make sure to use alias() as interpolation function, because hiera() will always return a string.

---
subnet01: '123.123.123.0/24'
subnet02: '123.123.124.0/24'
subnet03:
 - '123.123.125.0/24'
 - '123.123.126.0/24'

subnets:
  - "%{alias('subnet01')}"
  - "%{alias('subnet02')}"
  - "%{alias('subnet03')}"
  - 123.123.127.0/24

ferm::rules:
  'allow_http_https':
    chain: 'INPUT'
    action: 'ACCEPT'
    proto: 'tcp'
    dport:
      - 80
      - 443
    saddr: "%{alias('subnets')}"

ferm::rules is a hash. configured for deep merge. Hiera will collect all defined hashes and hand them over to the class. The main class will create rules for all of them. It also collects all exported resources that are tagged with the FQDN of a box.

It's also possible to match against ipsets. This allows to easily match against a huge amount of IP addresses or network ranges. You can use this as follows:

ferm::ipset { 'INPUT':
  sets => {
   'office'   => 'ACCPET',
   'internet' => 'DROP',
  }
}

please see the references section for more examples.

Examples

disable conntrack for all non-local destinations (e.g. for hypervisors)

General best practices for firewalling recommend that you use explicit whitelisting. Usually this boils down to configuring your firewall in a stateful manner, i.e. allowing ESTABLISHED and RELATED connections in addition to some whitelisted ports (i.e. TCP/22 for SSHD, likely limited to certain source addresses). For this to work you need connection tracking, provided by the nf_conntrack kernel module and configurable via the iptables conntrack module. However, especially in virtualization environments, you do not want to track every connection being routed through the hypervisor. You only want to track connections directly addressed to the hypervisor itself, i.e. traffic ending up in the filter/INPUT chain, but not traffic that is later going through filter/FORWARD to guest systems. Unfortunately the ferm tool does not allow negating lists (i.e. @ipfilter()) and thus we cannot easily negate saddr or daddr params, which forces us to configure two rules instead of one.

Connection tracking can only be controlled in the PREROUTING chain of the raw table.

ferm::rules:
  'allow_conntrack_local':
    chain: 'PREROUTING'
    table: 'raw'
    proto: 'all'
    daddr:
      - "%{facts.ipaddress}"
      - "%{facts.ipaddress6}"
    action: 'RETURN'
  'disable_conntrack_nonlocal':
    chain: 'PREROUTING'
    table: 'raw'
    proto: 'all'
    action: 'NOTRACK'
    interface: "%{facts.networking.primary}"

The upper RETURN rule will stop evaluating further rules in the PREROUTING chain of the raw table if the traffic is addressed directly to the current node applying the catalogue. The second rule will disable connection tracking for all other traffic coming in over the primary network interface, that is not addressed directly to the current node, i.e. guest systems hosted on it.

This will prevent your conntrack table from overflowing, tracking only the relevant connections and allowing you to use a stateful ruleset.

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

$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',
}

Reference

All parameters are documented within the classes. We generate markdown documentation. It's available in the REFERENCE.md. It also contains many examples.

Development

This project contains tests for rspec-puppet.

Quickstart to run all linter and unit tests:

bundle install --path .vendor/ --without system_tests --without development --without release
bundle exec rake test

For more details about the development workflow and on how to contribute, please check the CONTRIBUTING.md.

Authors

puppet-ferm is maintained by Vox Pupuli, it was written by Tim 'bastelfreak' Meusel.