firewall_multi

Overview

The firewall_multi module provides a defined type wrapper for spawning puppetlabs/firewall resources for arrays of certain inputs.

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.

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.

• destination: the destination IP address or network or an array of destinations.

• proto: the protocol or an array of protocols.

• icmp: the ICMP type or an array of ICMP types specified as an array of integers or strings.

• provider: the provider to use, either iptables or ip6tables.

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

Use of these supported array parameters causes firewall resources to be spawned for each address in the array. For example, in the case of the source parameter, and a string like 'from x.x.x.x/x' is 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 source.

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.

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:

Puppet 3.x or higher, where we can use the create_resources function:

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

And in Puppet >= 4.x, we can use iteration:

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

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

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

2017-11-16 - Version 1.10.0

• Update to support changes in firewall 1.10.0.

2017-10-01 - Version 1.9.0

• Update to support changes in firewall 1.9.0.

2017-10-01 - Version 1.8.0

• Update to support changes in firewall 1.8.2.

2017-10-01 - Version 1.7.0 (1.6.0 appears to have been skipped in error).

• Add some missing properties for firewall 1.8.0.
• Add the gen_params.sh script.
• Add compatibility matrix in docs.
• Other minor documentation changes.

2017-02-17 - Version 1.5.0

• Add feature providers (Issue #12)

2016-06-12 - Version 1.4.1

• Improved documentation (Issue #8)
• Workaround to Nokogiri install issue (Issue #9)
• Updated Gemfile config

2016-04-20 - Version 1.4.0

• Add feature for arrays of protocols (Mark McKinstry).

2016-04-10 - Version 1.3.1

• Add Beaker tests and nodesets for CentOS 7, 6, Ubuntu 14.04 and Debian 7 & 8.

2016-03-27 - Version 1.3.0

• (Issue 5) Add 4.x version of the custom function.
• Improvements to documentation.
• Travis CI integration added (Mark McKinstry).

2016-03-26 - Version 1.2.1

• Fix regression for Puppet 3.x.
  • workaround for https://tickets.puppetlabs.com/browse/PUP-2523
  • workaround for https://ask.puppetlabs.com/question/15677/custom-recursive-function-fails/

2016-03-24 - Version 1.2.0

• (Issue 3) Complete rewrite.

Using a custom function plus create_resources it was possible to vastly simplify the logic.

2016-03-18 - Version 1.1.3

• (Issue 2) Bugfix for undefined variable warning.

2016-03-16 - Version 1.1.2

• Clean up code
• Add unpack function
• add unit tests for functions.

2016-03-15 - Version 1.1.1

• Fix typos in README.md.

2016-03-15 - Version 1.1.0

• (Issue 1) Add feature supporting arrays of ICMP types.
• Improved design
  • source and destination now default to undef
  • if passed undef, there is no 'from 0.0.0.0/0' added in the title.

2016-03-11 - Version 1.0.5

• Add PE support to metadata.json.

2016-03-09 - Version 1.0.4

• Clarify that only puppetlabs/firewall 1.8.0 and later is supported.

2016-03-08 - Version 1.0.3

• Ok, satisfy Forge's lint rather than my preferred lint config.

2016-03-07 - Version 1.0.2

• Fix up styling to satisfy lint
• Modify lint config
• Updates documentation

2016-03-07 - Version 1.0.1

• Initial public release