A multiplexer frontend for puppetlabs/firewall
Ruby Puppet
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib/puppet
manifests
spec
tests
.fixtures.yml
.gitignore
.travis.yml
CHANGELOG
CONTRIBUTING.md
Gemfile
LICENSE
README.md
Rakefile
metadata.json

README.md

firewall_multi

Build Status

Overview

The firewall_multi module provides a defined type wrapper for spawning puppetlabs/firewall resources for arrays of certain inputs, namely sources, destinations, protocols and ICMP types.

Usage

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.

Parameters

  • source: the source IP address or network or an array of sources. Use of this parameter causes a firewall resource to be spawned for each address in the array of sources, and a string like 'from x.x.x.x/x' to be appened to each spawned resource's title to guarantee uniqueness in the catalog. If not specified, a default of undef is used and the resultant firewall resource provider will not be passed a source.

  • destination: the destination IP address or network or an array of destinations. Use of this parameter causes a firewall resource to be spawned for each address in the array of destinations, and a string like 'to y.y.y.y/y' to be appended to each spawned resource's title to guarantee uniqueness in the catalog. If not specified, a default of undef is used and the resultant firewall resource provider will not be passed a destination.

  • proto: the protocol or an array of protocols. Use of this parameter causes a firewall resource to be spawned for each protocol in the array of protocols, and a string like 'protocol aa' to be appended to each spawned resource's title to guarantee uniqueness in the catalog. If not specified, a default of undef is used and the resultant firewall resource provider will not be passed a protocol.

  • icmp: the ICMP type or an array of ICMP types specified as an array of integers or strings. Use of this parameter causes a firewall resource to be spawned for each type in the array of ICMP types, and a string like 'icmp type nn' to be appended to each spawned resource's title to guarantee uniqueness in the catalog. If not specified, a default of undef is used and the resultant firewall resource provider will not be passed an ICMP type.

  • Any other parameter accepted by firewall is also accepted and set for each firewall resource created without error-checking.

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

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.

Use with Hiera and create_resources

Some users may prefer to externalise the firewall resources in Hiera and use the create_resources function:

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

Puppet 3.x:

class myclass (
  $firewall_multis,
) {
  validate_hash($firewall_multis)
  create_resources(firewall_multi, $firewall_multis)
  ...
}

Puppet 4.x:

class myclass (
  Hash $firewall_multis,
) {
  create_resources(firewall_multi, $firewall_multis)
  ...
}

The alias lookup

Users who wish to externalise the firewall resources in Hiera should be aware of a feature that was added to Hiera in version 3, namely 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')}"

Known Issues

If you are using Puppet 3.x please understand the implications of Issue #5.

At the moment, only the latest version of puppetlabs/firewall is supported, namely >= 1.8.0. If this is a problem for you, raise an issue and I'll fix it.

This module does not sanity-check the proposed inputs for the resultant firewall resources. We assume that we can rely on the firewall resource types themselves to detect invalid inputs.

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