firewall_multi

A multiplexer frontend for puppetlabs/firewall

Project URL RSS Feed Report issues

Module Stats

338,324 downloads

169 latest version

4.3 quality score

Version information

released Feb 18th 2017

This version is compatible with:

Puppet Enterprise >= 3.0.0 < 2015.4.0
Puppet >= 3.0.0 < 5.0.0
, , , , , , ,

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'alexharvey-firewall_multi', '1.5.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.5.0

Documentation

alexharvey/firewall_multi — version 1.5.0 Feb 18th 2017

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
protocol
icmp
provider

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

##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 { '100 allow http and https access':
  dport    => [80, 443],
  proto    => 'tcp',
  action   => 'accept',
  provider => ['ip6tables', '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 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

The MIT License (MIT)

Copyright (c) 2016 Alex Harvey

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Modules

Discover

Contribute

Resources

About Forge

Getting Started

firewall_multi

Approved

Version information

This version is compatible with:

Start using this module

Documentation

firewall_multi

Array of sources

Arrays of sources and destinations

Array of protocols

Array of ICMP types

Array of providers

Used in place of a single firewall resource

Use with Hiera and create_resources

The alias lookup

Dependencies