- Overview
- Support status
- Version compatibility
- Setup
- Reference - Defined types - Functions
- Development
- Troubleshooting
- Donate
The firewall_multi module provides a defined type wrapper for spawning puppetlabs/firewall resources from arrays of certain inputs. This is useful at large sites with many networks, because puppetlabs-firewall accepts only scalar values for those inputs. The limitation comes from the underlying Linux iptables command, which does not support multiple values for every option.
(For more information about the history and motivation for this project, see MODULES-3066 in the Puppet Jira.)
Currently, the following inputs can be arrays:
- source
- destination
- proto
- icmp
- protocol
This module is maintained and supported. However, I do not always see GitHub notifications. If I do not immediately respond, send me an email.
Each release of the firewall_multi module is compatible with a specific release of puppetlabs-firewall, starting at firewall v1.8.0. Earlier versions of the firewall module are not supported.
| firewall_multi | firewall |
|---|---|
| earlier | 1.8.0 |
| 1.7.0 | 1.8.0, 1.8.1 |
| 1.8.0 | 1.8.2 |
| 1.9.0 | 1.9.0 |
| 1.10.1 | 1.10.0, 1.11.0, 1.12.0, 1.13.0, 1.14.0 |
| 1.11.0 | 1.10.0, 1.11.0, 1.12.0, 1.13.0, 1.14.0 |
| 1.12.0 | 1.15.0, 1.15.1 |
| 1.13.0 | 1.15.2, 1.15.3 |
| 1.13.1 | 1.15.3 |
| 1.13.2 | 1.15.3 |
| 1.14.0 | 2.0.0 |
| 1.14.1 | 2.0.0 |
| 1.15.0 | 2.1.0 |
| 1.16.0 | 2.2.0 |
| 1.17.0 | 2.3.0 |
| 1.18.0 | 2.4.0 |
| 1.19.0 | 2.5.0, 2.6.0, 2.7.0 |
| 1.20.0 | 2.8.0, 2.8.1 |
| 3.0.0 | 3.0.0, 3.0.1, 3.0.2, 3.1.0, 3.2.0, 3.3.0 |
| 3.4.0 | 3.4.0 |
| 3.5.0 | 3.5.0, 3.6.0 |
| 4.0.0 | 4.0.0 |
| 4.0.1 | 4.0.1, 4.1.0 |
| 5.0.0 | 5.0.0 |
| 6.0.0 | 6.0.0 |
| 7.0.0 | 7.0.0, 7.0.1, 7.0.2 |
| 7.0.1 | 7.0.0, 7.0.1, 7.0.2 |
| 7.0.2 | 7.0.0, 7.0.1, 7.0.2 |
| 7.0.3 | 7.0.0, 7.0.1, 7.0.2 |
| 8.0.0 | 8.0.0 |
| 8.0.1 | 8.0.1, 8.0.2, 8.0.3, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.2.0, 8.3.0 |
| 8.4.0 | 8.4.0 |
| 8.4.1 | 8.4.0 |
Puppet 3 support was dropped in version 1.11.0. The versioning was changed to 3.0.0 to match upstream firewall versioning, without any code changes.
The scope is the same as with the firewall module.
The firewall_multi module's only dependency is the firewall module.
It is expected that the firewall module is configured normally, in particular with respect to purging firewall resources. If, for instance, addresses are removed from an array of sources, the corresponding firewall resources are only removed if purging is enabled. This might be surprising in a way that impacts security.
Otherwise, usage of the firewall_multi defined type is the same as with the firewall custom type, the only exceptions being that some parameters optionally accept arrays.
Before upgrading, read the version compatibility matrix above. Versions of this module sometimes must be kept in sync with the firewall module.
To upgrade the module, use the puppet module tool as normal:
puppet module upgrade alexharvey/firewall_multi
firewall_multi: A defined type wrapper for spawning puppetlabs/firewall resources for arrays of certain inputs.
firewall_multi: Take a name and a hash and return a modified hash suitable for input to create_resources().
A defined type wrapper for spawning puppetlabs/firewall resources for arrays of certain inputs.
The following parameters are available in the firewall_multi defined type:
Type: Ruby 4.x API
Convert firewall_multi type data to firewall type data.
- Note Given this input:
[
{
"00100 accept inbound ssh" => {
"jump" => "accept",
"source" => ["1.1.1.1/24", "2.2.2.2/24"],
"dport" => 22,
},
}
]Return this:
{
"00100 accept inbound ssh from 1.1.1.1/24" => {
"jump" => "accept",
"source" => "1.1.1.1/24",
"dport" => 22,
},
"00100 accept inbound ssh from 2.2.2.2/24" => {
"jump" => "accept",
"source" => "2.2.2.2/24",
"dport" => 22,
},
}Convert firewall_multi type data to firewall type data.
Returns: Any Modified Hash for firewall types to be passed to create_resources().
Data type: Hash
The original resource params data.
firewall_multi { '100 allow http and https access':
source => [
'10.0.10.0/24',
'10.0.12.0/24',
'10.1.1.128',
],
dport => [80, 443],
proto => tcp,
jump => accept,
}This will cause three resources to be created:
- Firewall['100 allow http and https access from 10.0.10.0/24']
- Firewall['100 allow http and https access from 10.0.12.0/24']
- Firewall['100 allow http and https access from 10.1.1.128']
firewall_multi { '100 allow http and https access':
source => [
'10.0.10.0/24',
'10.0.12.0/24',
],
destination => [
'10.2.0.0/24',
'10.3.0.0/24',
],
dport => [80, 443],
proto => tcp,
jump => accept,
}This will cause four resources to be created:
- Firewall['100 allow http and https access from 10.0.10.0/24 to 10.2.0.0/24']
- Firewall['100 allow http and https access from 10.0.10.0/24 to 10.3.0.0/24']
- Firewall['100 allow http and https access from 10.0.12.0/24 to 10.2.0.0/24']
- Firewall['100 allow http and https access from 10.0.12.0/24 to 10.3.0.0/24']
firewall_multi { '100 allow DNS lookups':
dport => 53,
proto => ['tcp', 'udp'],
jump => 'accept',
}This will cause two resources to be created:
- Firewall['100 allow DNS lookups proto tcp']
- Firewall['100 allow DNS lookups proto udp']
firewall_multi { '100 accept icmp output':
chain => 'OUTPUT',
proto => 'icmp',
jump => 'accept',
icmp => [0, 8],
}This will cause two resources to be created:
- Firewall['100 accept icmp output icmp type 0']
- Firewall['100 accept icmp output icmp type 8']
Open a firewall for IPv4 and IPv6 on a web server:
firewall_multi { '100 allow http and https access':
dport => [80, 443],
proto => 'tcp',
jump => 'accept',
protocol => ['ip6tables', 'iptables'],
}This will cause two resources to be created:
- Firewall['100 allow http and https access using protocol ip6tables']
- Firewall['100 allow http and https access using protocol iptables']
Some users may prefer to externalise firewall resources in Hiera. For example:
---
myclass::firewall_multis:
'00099 accept tcp port 22 for ssh':
dport: '22'
jump: 'accept'
proto: 'tcp'
source:
- 10.0.0.3/32
- 10.10.0.0/26Meanwhile, manifest code would look something like this:
class myclass (
Hash[String, Hash] $firewall_multis,
) {
$firewall_multis.each |$name, $firewall_multi| {
firewall_multi { $name:
* => $firewall_multi
}
}
...
}Or:
class myclass (
Hash[String, Hash] $firewall_multis,
) {
create_resources(firewall_multi, $firewall_multis)
...
}Those who externalise firewall resources in Hiera should be aware of the alias lookup function, which makes it possible to define networks as arrays in Hiera and then look these up from within the firewall_multi definitions.
The following examples show how to do that:
---
mylocaldomains:
- 10.0.0.3/32
- 10.10.0.0/26
myotherdomains:
- 172.0.1.0/26
myclass::firewall_multis:
'00099 accept tcp port 22 for ssh':
dport: '22'
jump: 'accept'
proto: 'tcp'
source: "%{alias('mylocaldomains')}"
'00200 accept tcp port 80 for http':
dport: '80'
jump: 'accept'
proto: 'tcp'
source: "%{alias('myotherdomains')}"Please read CONTRIBUTING.md before contributing.
Make sure you have:
- rake
- bundler
Use the project Ruby version:
rbenv install 3.2.0
rbenv local 3.2.0
The project does not check in Gemfile.lock. If you already have an ignored
local lockfile, remove it before installing; stale local lockfiles can pin old
test helpers and break the Rake tasks.
Configure Bundler:
bundle config set specific_platform true
rm -f Gemfile.lock
Install the necessary gems:
bundle install
The Rakefile is the source of truth for project checks. To run the same build checks used by CI from the root of the source code:
bundle exec rake ci:build
For a narrower local loop, run individual tasks:
bundle exec rake validate
bundle exec rake lint
bundle exec rake spec
bundle exec rake docs:check
bundle exec rake generated_manifest:check
bundle exec rake security:bundle_audit
bundle exec rake module:install_check
To run the Litmus acceptance tests locally, ensure Docker is running, then use:
bundle exec rake ci:acceptance
bundle exec rake ci:acceptance_teardown
This module uses Puppet Blacksmith to publish to the Puppet Forge.
Before releasing, run the release consistency checks:
bundle exec rake release:check
Releases are published automatically when a version tag is pushed:
git tag 8.4.1
git push origin 8.4.1
The GitHub release workflow expects these repository secrets:
BLACKSMITH_FORGE_USERNAME
BLACKSMITH_FORGE_API_KEY
For manual local releases, ensure you have these lines in ~/.bash_profile:
export BLACKSMITH_FORGE_URL=https://forgeapi.puppetlabs.com
export BLACKSMITH_FORGE_USERNAME=alexharvey
export BLACKSMITH_FORGE_API_KEY=xxxxxxxx
Build the module and push to Forge:
bundle exec rake module:push
Clean the pkg directory. Otherwise, Blacksmith will try to push old copies to Forge next time you run it, and it will fail:
bundle exec rake module:clean
On occasion, users of this module have reported confusing failure messages like:
Error: no parameter named 'ipvs'
This is sometimes seen after upgrading.
The error message is probably not a bug in this module. First, check the version compatibility matrix above, and make sure you have installed a compatible combination of firewall/firewall_multi.
While this is not a problem with this module, firewall_multi is likely to fail when environment isolation is not configured correctly, because it must be pinned to a specific version of puppetlabs/firewall. Follow the docs in the previous link to resolve the issue. Also, be aware of how to use r10k to automatically generate types during deployments.
If you find that this code saved your project some significant time, consider donating:
Also, please add a star if you find it useful!