Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

firewall_multi

A multiplexer frontend for puppetlabs/firewall
Project URLRSS FeedReport issues

346,286 downloads

785 latest version

5.0 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

  • 8.0.1 (latest)
  • 8.0.0
  • 7.0.3
  • 7.0.2
  • 7.0.1
  • 7.0.0
  • 6.0.0
  • 5.0.0
  • 4.0.0
  • 3.5.0
  • 3.4.0
  • 3.0.0
  • 1.20.0
  • 1.19.0
  • 1.18.0
  • 1.17.0
  • 1.16.0
  • 1.15.0
  • 1.14.1
  • 1.14.0
  • 1.13.2
  • 1.13.1
  • 1.13.0
  • 1.12.0
  • 1.11.0
  • 1.10.1
  • 1.10.0
  • 1.9.0
  • 1.8.0
  • 1.7.0
  • 1.5.0
  • 1.4.1
  • 1.4.0
  • 1.3.1
  • 1.3.0
  • 1.2.1
  • 1.2.0
  • 1.1.3
  • 1.1.2
  • 1.1.1
  • 1.1.0
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0 (deleted)
released Nov 18th 2018
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 3.0.0 < 6.0.0
  • , , , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'alexharvey-firewall_multi', '1.11.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add alexharvey-firewall_multi
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install alexharvey-firewall_multi --version 1.11.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

alexharvey/firewall_multi — version 1.11.0 Nov 18th 2018

firewall_multi

Build Status

Table of contents

  1. Overview
  2. Version compatibility
  3. Setup
  4. Reference
  5. Development

Overview

The firewall_multi module provides a defined type wrapper for spawning 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 in the Puppet Jira.)

At present the following inputs can be arrays:

  • source
  • destination
  • proto
  • icmp
  • provider

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.7.0 1.8.1
1.8.0 1.8.2
1.9.0 1.9.0
1.10.1 1.10.0
1.10.1 1.11.0
1.10.1 1.12.0
1.10.1 1.13.0
1.10.1 1.14.0
1.11.0 1.10.0
1.11.0 1.11.0
1.11.0 1.12.0
1.11.0 1.13.0
1.11.0 1.14.0

Note that Puppet 3 support was dropped in version 1.11.0.

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 a user of this module, for instance, removes addresses from an array of sources, the corresponding firewall resources will only be removed if purging is enabled. This might be surprising to the user 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:

puppet module upgrade alexharvey/firewall_multi

Reference

Defined types

Functions

  • firewall_multi: Take a name and a hash and return a modified hash suitable for input to create_resources().

Defined types

firewall_multi

A defined type wrapper for spawning puppetlabs/firewall resources for arrays of certain inputs.

Examples
Array of sources

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,
  action => 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

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,
  action => 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 protocols

firewall_multi { '100 allow DNS lookups':
  dport  => 53,
  proto  => ['tcp', 'udp'],
  action => 'accept',
}

This will cause two resources to be created:

* Firewall['100 allow DNS lookups protocol tcp']
* Firewall['100 allow DNS lookups protocol udp']
Array of ICMP types

firewall_multi { '100 accept icmp output':
  chain  => 'OUTPUT',
  proto  => 'icmp',
  action => '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 providers

Open a firewall for IPv4 and IPv6 on a web server:

firewall_multi { '100 allow http and https access':
  dport    => [80, 443],
  proto    => 'tcp',
  action   => 'accept',
  provider => ['ip6tables', 'iptables'],
}

This will cause two resources to be created:

* Firewall['100 allow http and https access using provider ip6tables']
* Firewall['100 allow http and https access using provider iptables']
Used in place of a single firewall resource

If none of firewall_multi's array functionality is used, then the firewall_multi and firewall resources can be used interchangeably.
Parameters

The following parameters are available in the firewall_multi defined type.

source

Data type: Array

An array of source IPs or CIDRs.

Default value: undef

destination

Data type: Array

An array of destination IPs or CIDRs.

Default value: undef

proto

Data type: Array

An array of protocols.

Default value: undef

icmp

Data type: Array

An array of ICMP types.

Default value: undef

provider

Data type: Array

An array of providers.

Default value: undef

Functions

firewall_multi

Type: Ruby 4.x API

Convert firewall_multi type data to firewall type data.

  • Note It would be more natural to accept input structured as:
[
  {
    '00100 accept inbound ssh' => {
      'action' => 'accept',
      'source' => ['1.1.1.1/24', '2.2.2.2/24'],
      'dport'  => 22,
    },
  }
]

It was implemented this way when Puppet 3 was supported to work around PUP-2523.

firewall_multi(String $name, Hash $hash)

Convert firewall_multi type data to firewall type data.

Returns: Any Modified Hash for firewall types to be passed to create_resources().

name

Data type: String

The original resource title.

hash

Data type: Hash

The original resource params data.

Use with Hiera

Some users may prefer to externalise the firewall resources in Hiera:

---
myclass::firewall_multis:
  '00099 accept tcp port 22 for ssh':
    dport: '22'
    action: 'accept'
    proto: 'tcp'
    source:
      - 10.0.0.3/32
      - 10.10.0.0/26

Meanwhile we would have manifest code that looks something like this:

class myclass (
  Hash $firewall_multis,
) {
  $firewall_multis.each |$name, $firewall_multi| {
    firewall_multi { $name:
      * => $firewall_multi
    }
  }
  ...
}

The alias lookup

Users who wish to externalise the 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'
    action: 'accept'
    proto: 'tcp'
    source: "%{alias('mylocaldomains')}"
  '00200 accept tcp port 80 for http':
    dport: '80'
    action: 'accept'
    proto: 'tcp'
    source: "%{alias('myotherdomains')}"

Development

Please read CONTRIBUTING.md before contributing.

Testing

Make sure you have:

  • rake
  • bundler

Install the necessary gems:

bundle install

To run the tests from the root of the source code:

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_PASSWORD=xxxxxxxxx

Build the module:

bundle exec rake build

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