Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alex-harvey-z3q/puppet-firewall_multi
A multiplexer frontend for puppetlabs/firewall
https://github.com/alex-harvey-z3q/puppet-firewall_multi
puppet
Last synced: 9 days ago
JSON representation
A multiplexer frontend for puppetlabs/firewall
- Host: GitHub
- URL: https://github.com/alex-harvey-z3q/puppet-firewall_multi
- Owner: alex-harvey-z3q
- License: mit
- Created: 2016-02-19T03:04:53.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-12-29T04:54:32.000Z (about 1 month ago)
- Last Synced: 2025-01-30T08:08:58.486Z (10 days ago)
- Topics: puppet
- Language: Puppet
- Homepage:
- Size: 269 KB
- Stars: 10
- Watchers: 5
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# firewall_multi
[](https://github.com/alex-harvey-z3q/puppet-firewall_multi/actions/workflows/build.yaml)
#### Table of contents
1. [Overview](#overview)
2. [Support status](#support-status)
3. [Version compatibility](#version-compatibility)
4. [Setup](#setup)
* [What firewall_multi affects](#what-firewall_multi-affects)
* [Setup requirements](#setup-requirements)
* [Beginning with firewall_multi](#beginning-with-firewall_multi)
* [Upgrading](#upgrading)
5. [Reference](#reference)
- [Defined types](#defined-types)
- [Functions](#functions)
* [Defined types](#defined-types-2)
- [`firewall_multi`](#a-namefirewall_multiafirewall_multi)
* [Functions](#functions-2)
- [`firewall_multi`](#a-namefirewall_multiafirewall_multi-2)
* [Examples](#examples)
- [Array of sources](#array-of-sources)
- [Arrays of sources and destinations](#arrays-of-sources-and-destinations)
- [Array of proto's](#array-of-protos)
- [Array of ICMP types](#array-of-icmp-types)
- [Array of protocols](#array-of-protocols)
* [Use with Hiera](#use-with-hiera)
* [The alias lookup](#the-alias-lookup)
6. [Development](#development)
* [Testing](#testing)
* [Release](#release)
7. [Troubleshooting](#troubleshooting)
* ["Error: no parameter named X"](#error-no-parameter-named-x)
* [Resolution 1 - ensure you have the right version](#resolution-1---ensure-you-have-the-right-version)
* [Resolution 2 - environment isolation](#resolution-2---environment-isolation)
8. [Donate](#donate)
## Overview
The `firewall_multi` module provides a defined type wrapper for spawning [puppetlabs/firewall](https://github.com/puppetlabs/puppetlabs-firewall) resources for arrays of certain inputs. This is useful at large sites that may have many networks, due to the puppetlabs-firewall module lacking functionality to allow arrays for certain inputs. The limitation is due to the underlying Linux iptables command, which also only allows arrays for certain inputs.
(For more information about the history and motivation for this project, see [MODULES-3066](https://tickets.puppetlabs.com/browse/MODULES-3066) in the Puppet Jira.)
At present the following inputs can be arrays:
* source
* destination
* proto
* icmp
## Support status
This module is maintained and supported. However, I do not always see GitHub notifications. If I do not immediately respond, send me an email.
## Version compatibility
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
Note that Puppet 3 support was dropped in version 1.11.0. Note that the versioning was changed to 3.0.0 to match the upstream versioning without any changes made.
## Setup
### What firewall_multi affects
The scope is the same as with the firewall module.
### Setup requirements
The firewall_multi module's only dependency is the firewall module.
### Beginning with firewall_multi
It is expected that a standard set up for the firewall module is followed, in particular with respect to the purging of firewall resources. If, for instance, addresses are removed from an array of sources, the corresponding firewall resources would only be 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.
### Upgrading
Firstly, ensure you have read the version compatibility matrix section above before upgrading as 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:
~~~ text
puppet module upgrade alexharvey/firewall_multi
~~~
## Reference
#### Defined types
* [`firewall_multi`](#firewall_multi): A defined type wrapper for spawning
[puppetlabs/firewall](https://github.com/puppetlabs/puppetlabs-firewall)
resources for arrays of certain inputs.
#### Functions
* [`firewall_multi`](#firewall_multi): Take a name and a hash and return a modified hash suitable
for input to create_resources().
### Defined types
A defined type wrapper for spawning
[puppetlabs/firewall](https://github.com/puppetlabs/puppetlabs-firewall)
resources for arrays of certain inputs.
##### Parameters
The following parameters are available in the `firewall_multi` defined type:
* [`source`](#-firewall_multi--source)
* [`destination`](#-firewall_multi--destination)
* [`proto`](#-firewall_multi--proto)
* [`icmp`](#-firewall_multi--icmp)
### Functions
Type: Ruby 4.x API
Convert firewall_multi type data to firewall type data.
* **Note** Given this input:
```ruby
[
{
"00100 accept inbound ssh" => {
"jump" => "accept",
"source" => ["1.1.1.1/24", "2.2.2.2/24"],
"dport" => 22,
},
}
]
```
Return this:
```ruby
{
"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,
},
}
```
##### `firewall_multi(Hash $hash)`
Convert firewall_multi type data to firewall type data.
Returns: `Any` Modified Hash for firewall types to be passed to create_resources().
###### `hash`
Data type: `Hash`
The original resource params data.
### Examples
#### Array of sources
```puppet
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']
#### Arrays of sources and destinations
```puppet
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']
#### Array of proto's
```puppet
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']
#### Array of ICMP types
```puppet
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']
#### Array of protocols
Open a firewall for IPv4 and IPv6 on a web server:
```puppet
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']
### Use with Hiera
Some users may prefer to externalise firewall resources in Hiera. For example:
```yaml
---
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/26
```
Meanwhile, manifest code would look something like this:
```puppet
class myclass (
Hash[String, Hash] $firewall_multis,
) {
$firewall_multis.each |$name, $firewall_multi| {
firewall_multi { $name:
* => $firewall_multi
}
}
...
}
```
Or:
```puppet
class myclass (
Hash[String, Hash] $firewall_multis,
) {
create_resources(firewall_multi, $firewall_multis)
...
}
```
### The alias lookup
Those who externalise firewall resources in Hiera should be aware of the [alias lookup function](https://docs.puppet.com/hiera/3.0/variables.html#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:
```yaml
---
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')}"
```
## Development
Please read CONTRIBUTING.md before contributing.
### Testing
Make sure you have:
* rake
* bundler
Pre config:
bundle config set specific_platform true
rm -f Gemfile.lock
Install the necessary gems:
bundle install --path vendor/bundle
To run the tests from the root of the source code:
bundle exec rake spec_prep
bundle exec rake spec
To run the acceptance tests:
BEAKER_set=centos-72-x64 bundle exec rspec spec/acceptance
### Release
This module uses Puppet Blacksmith to publish to the Puppet Forge.
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 dir (otherwise Blacksmith will try to push old copies to Forge next time you run it and it will fail):
bundle exec rake module:clean
## Troubleshooting
### "Error: no parameter named X"
On [occasion](https://github.com/alexharv074/puppet-firewall_multi/issues/19), users of this module have reported confusing failure error messages like:
```text
Error: no parameter named 'ipvs'
```
Sometimes seen after upgrading.
### Resolution 1 - ensure you have the right version
The error message is probably not a bug in this module. Firstly, ensure that you have checked the [version compatibility](#version-compatibility) matrix above, and have installed a compatible combination of firewall/firewall_multi.
### Resolution 2 - environment isolation
While not a problem with this module, this module - due to its requirement to be pinned against a very specific version of puppetlabs/firewall - is a likely candidate for failing if you have not properly set up [environment isolation](https://puppet.com/docs/puppet/6.4/environment_isolation.html). Follow the docs in the previous link to resolve the issue. Also, be aware of how to use r10k to automatically [generate types](https://github.com/puppetlabs/r10k/blob/master/doc/faq.mkd#how-can-run-i-puppet-generate-types-for-each-changed-environment-during-deployment) during deployments.
## Donate
If you find that this code saved your project some significant time, consider donating:
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6849RBYT6VYBQ)
Also, please add a star if you find it useful!