firewall

Firewall Module

Project URL RSS Feed Report issues

Module Stats

10,530,056 downloads

3,748 latest version

4.1 quality score

Version information

released Mar 4th 2013

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'puppetlabs-firewall', '0.2.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-firewall

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-firewall --version 0.2.0

Tags: debian, ubuntu, redhat, iptables, security, firewall, ip6tables, archlinux, centos

Documentation

puppetlabs/firewall — version 0.2.0 Mar 4th 2013

puppetlabs-firewall module

User Guide

Overview

This module provides the resource 'firewall' which provides the capability to manage firewall rules within puppet.

Current support includes:

iptables
ip6tables

With the resource 'firewallchain' we also provide a mechanism to manage chains for:

iptables
ip6tables
ebtables

Disclaimer

Warning! While this software is written in the best interest of quality it has not been formally tested by our QA teams. Use at your own risk, but feel free to enjoy and perhaps improve it while you do.

Please see the included Apache Software License for more legal details regarding warranty.

Also as this is a 0.x release the API is still in flux and may change. Make sure you read the release notes before upgrading.

Downloading

If you are intending to use this module it is recommended you obtain this from the forge and not Github:

http://forge.puppetlabs.com/puppetlabs/firewall

The forge releases are vetted releases. Using code from Github means you are accessing a development version or early release of the code.

Installation

Using the puppet-module gem, you can install it into your Puppet's module path. If you are not sure where your module path is try this command:

puppet --configprint modulepath

Firstly change into that directory. For example:

cd /etc/puppet/modules

Then run the module tool:

puppet-module install puppetlabs-firewall

This module uses both Ruby based providers so your Puppet configuration (ie. puppet.conf) must include the following items:

[agent]
pluginsync = true

The module will not operate normally without these features enabled for the client.

If you are using environments or with certain versions of Puppet you may need to run Puppet on the master first:

puppet agent -t --pluginsync --environment production

You may also need to restart Apache, although this shouldn't always be the case.

Recommended Setup

There are a basic set of classes which manage packages and services for the currently supported operating systems:

include firewall

At the moment you need to provide some setup outside of what we provide in the module to support proper ordering and purging.

Persistence of rules between reboots is handled automatically for the supported distributions listed below. Although there are known issues with ip6tables on older Debian/Ubuntu and ebtables.

It is recommended that you provide the following in top scope somewhere (such as your site.pp):

# Purge unmanaged firewall resources
#
# This will clear any existing rules, and make sure that only rules
# defined in puppet exist on the machine
resources { "firewall":
  purge => true
}

# These defaults ensure that the pre & post classes are run in the right
# order to avoid potentially locking you out of your box during the
# first puppet run.
Firewall {
  before  => Class['my_fw::post'],
  require => Class['my_fw::pre'],
}

You also need to declare the 'my_fw::pre' & 'my_fw::post' classes so that dependencies are satisfied. This can be achieved using an External Node Classifier or the following::

class { 'my_fw::pre': }
class { 'my_fw::post': }

or:

include my_fw::pre, my_fw:post

In this case, it uses classes called 'my_fw::pre' & 'my_fw::post' to define default pre and post rules. These rules are required to run in catalog order to avoid locking yourself out of your own boxes when Puppet runs, as the firewall class applies rules as it processes the catalog.

An example of the pre class would be:

# This would be located in my_fw/manifests/pre.pp
class my_fw::pre {
  Firewall {
    require => undef,
  }

  # Default firewall rules
  firewall { '000 accept all icmp':
    proto   => 'icmp',
    action  => 'accept',
  }->
  firewall { '001 accept all to lo interface':
    proto   => 'all',
    iniface => 'lo',
    action  => 'accept',
  }->
  firewall { '002 accept related established rules':
    proto   => 'all',
    state   => ['RELATED', 'ESTABLISHED'],
    action  => 'accept',
  }
}

And an example of a post class:

# This would be located in my_fw/manifests/post.pp:
class my_fw::post {
  firewall { '999 drop all':
    proto   => 'all',
    action  => 'drop',
    before  => undef,
  }
}

Examples

Basic accept ICMP request example:

firewall { "000 accept all icmp requests":
  proto  => "icmp",
  action => "accept",
}

Drop all:

firewall { "999 drop all other requests":
  action => "drop",
}

Source NAT example (perfect for a virtualization host):

firewall { '100 snat for network foo2':
  chain    => 'POSTROUTING',
  jump     => 'MASQUERADE',
  proto    => 'all',
  outiface => "eth0",
  source   => '10.1.2.0/24',
  table    => 'nat',
}

Creating a new rule that forwards to a chain, then adding a rule to this chain:

firewall { '100 forward to MY_CHAIN':
  chain   => 'INPUT',
  jump    => 'MY_CHAIN',
}
# The namevar here is in the format chain_name:table:protocol
firewallchain { 'MY_CHAIN:filter:IPv4':
  ensure  => present,
}
firewall { '100 my rule':
  chain   => 'MY_CHAIN',
  action  => 'accept',
  proto   => 'tcp',
  dport   => 5000,
}

Further documentation

More documentation is available from the forge for each release:

<http://forge.puppetlabs.com/puppetlabs/firewall>

Or you can access the inline documentation:

puppet describe firewall

Or:

puppet doc -r type

(and search for firewall).

Bugs

Bugs can be reported using Github Issues:

http://github.com/puppetlabs/puppetlabs-firewall/issues

Please note, we only aim support for the following distributions and versions:

Redhat 5.8 or greater
Debian 6.0 or greater
Ubuntu 11.04 or greater

If you want a new distribution supported feel free to raise a ticket and we'll consider it. If you want an older revision supported we'll also consider it, but don't get insulted if we reject it. Specifically, we will not consider Redhat 4.x support - its just too old.

Developer Guide

Contributing

Make sure you read CONTRIBUTING.md before contributing.

Currently we support:

iptables
ip6tables
ebtables (chains only)

But plans are to support lots of other firewall implementations:

FreeBSD (ipf)
Mac OS X (ipfw)
OpenBSD (pf)
Cisco (ASA and basic access lists)

If you have knowledge in these technology, know how to code and wish to contribute to this project we would welcome the help.

Testing

Make sure you have:

rake

Install the necessary gems:

gem install rspec

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

rake test

Types in this module release

firewallchain

This type provides the capability to manage rule chains for firewalls.

Currently this supports only iptables, ip6tables and ebtables on Linux. And
provides support for setting the default policy on chains and tables that
allow it.

**Autorequires:**
If Puppet is managing the iptables or iptables-persistent packages, and
the provider is iptables_chain, the firewall resource will autorequire
those packages to ensure that any required binaries are installed.

Parameters
ensure
name	The canonical name of the chain. `For iptables the format must be {chain}:{table}:{protocol}.`
provider

Properties
policy	This is the action to when the end of the chain is reached. It can only be set on inbuilt chains (INPUT, FORWARD, OUTPUT, PREROUTING, POSTROUTING) and can be one of: `* accept - the packet is accepted * drop - the packet is dropped * queue - the packet is passed userspace * return - the packet is returned to calling (jump) queue or the default of inbuilt chains`

Providers
iptables_chain

firewall

This type provides the capability to manage firewall rules within puppet.

**Autorequires:**

If Puppet is managing the iptables or ip6tables chains specified in the
`chain` or `jump` parameters, the firewall resource will autorequire
those firewallchain resources.

If Puppet is managing the iptables or iptables-persistent packages, and
the provider is iptables or ip6tables, the firewall resource will
autorequire those packages to ensure that any required binaries are
installed.

Parameters
ensure	Manage the state of this rule. The default action is present.
line	Read-only property for caching the rule line.
name	The canonical name of the rule. This name is also used for ordering so make sure you prefix the rule with a number: `000 this runs first 999 this runs last Depending on the provider, the name of the rule can be stored using the comment feature of the underlying firewall subsystem.`
provider

Properties
action	This is the action to perform on a match. Can be one of: `* accept - the packet is accepted * reject - the packet is rejected with a suitable ICMP response * drop - the packet is dropped If you specify no value it will simply match the rule but perform no action unless you provide a provider specific parameter (such as jump).`
burst	Rate limiting burst value (per second) before limit checks apply.
chain	Name of the chain to use. Can be one of the built-ins: `* INPUT * FORWARD * OUTPUT * PREROUTING * POSTROUTING Or you can provide a user-based chain. The default value is 'INPUT'.`
destination	The destination address to match. For example: `destination => '192.168.1.0/24' The destination can also be an IPv6 address if your provider supports it.`
dport	The destination port to match for this filter (if the protocol supports ports). Will accept a single element or an array. `For some firewall providers you can pass a range of ports in the format: <start_number>-<ending_number> For example: 1-1024 This would cover ports 1 to 1024.`
gid	GID or Group owner matching rule. Accepts a string argument only, as iptables does not accept multiple gid in a single statement.
icmp	When matching ICMP packets, this is the type of ICMP packet to match. `A value of "any" is not supported. To achieve this behaviour the parameter should simply be omitted or undefined.`
iniface	Input interface to filter on.
jump	The value for the iptables --jump parameter. Normal values are: `* QUEUE * RETURN * DNAT * SNAT * LOG * MASQUERADE * REDIRECT * MARK But any valid chain name is allowed. For the values ACCEPT, DROP and REJECT you must use the generic 'action' parameter. This is to enfore the use of generic parameters where possible for maximum cross-platform modelling. If you set both 'accept' and 'jump' parameters, you will get an error as only one of the options should be set.`
limit	Rate limiting value for matched packets. The format is: rate/[/second/\|/minute\|/hour\|/day]. `Example values are: '50/sec', '40/min', '30/hour', '10/day'."`
log_level	When combined with jump => "LOG" specifies the system log level to log to.
log_prefix	When combined with jump => "LOG" specifies the log prefix to use when logging.
outiface	Output interface to filter on.
pkttype	Sets the packet type to match.
port	The destination or source port to match for this filter (if the protocol supports ports). Will accept a single element or an array. `For some firewall providers you can pass a range of ports in the format: <start_number>-<ending_number> For example: 1-1024 This would cover ports 1 to 1024.`
proto	The specific protocol to match for this rule. By default this is tcp.
reject	When combined with jump => "REJECT" you can specify a different icmp response to be sent back to the packet sender.
set_mark	Set the Netfilter mark value associated with the packet. Accepts either of: mark/mask or mark. These will be converted to hex if they are not already.
socket	If true, matches if an open socket can be found by doing a coket lookup on the packet.
source	The source address. For example: `source => '192.168.2.0/24' The source can also be an IPv6 address if your provider supports it.`
sport	The source port to match for this filter (if the protocol supports ports). Will accept a single element or an array. `For some firewall providers you can pass a range of ports in the format: <start_number>-<ending_number> For example: 1-1024 This would cover ports 1 to 1024.`
state	Matches a packet based on its state in the firewall stateful inspection table. Values can be: `* INVALID * ESTABLISHED * NEW * RELATED`
table	Table to use. Can be one of: `* nat * mangle * filter * raw * rawpost By default the setting is 'filter'.`
tcp_flags	Match when the TCP flags are as specified. Is a string with a list of comma-separated flag names for the mask, then a space, then a comma-separated list of flags that should be set. The flags are: SYN ACK FIN RST URG PSH ALL NONE Note that you specify them in the order that iptables --list-rules would list them to avoid having puppet think you changed the flags. Example: FIN,SYN,RST,ACK SYN matches packets with the SYN bit set and the ACK,RST and FIN bits cleared. Such packets are used to request TCP connection initiation.
todest	When using jump => "DNAT" you can specify the new destination address using this paramter.
toports	For DNAT this is the port that will replace the destination port.
tosource	When using jump => "SNAT" you can specify the new source address using this parameter.
uid	UID or Username owner matching rule. Accepts a string argument only, as iptables does not accept multiple uid in a single statement.

Providers
ip6tables
iptables

puppetlabs-firewall changelog

Release notes for puppetlabs-firewall module.

0.2.0 - 2012/3/3

This release introduces automatic persistence, removing the need for the previous manual dependency requirement for persistent the running rules to the OS persistence file.

Previously you would have required the following in your site.pp (or some other global location):

# Always persist firewall rules
exec { 'persist-firewall':
  command     => $operatingsystem ? {
    'debian'          => '/sbin/iptables-save > /etc/iptables/rules.v4',
    /(RedHat|CentOS)/ => '/sbin/iptables-save > /etc/sysconfig/iptables',
  },
  refreshonly => true,
}
Firewall {
  notify  => Exec['persist-firewall'],
  before  => Class['my_fw::post'],
  require => Class['my_fw::pre'],
}
Firewallchain {
  notify  => Exec['persist-firewall'],
}
resources { "firewall":
  purge => true
}

You only need:

class { 'firewall': }
Firewall {
  before  => Class['my_fw::post'],
  require => Class['my_fw::pre'],
}

To install pre-requisites and to create dependencies on your pre & post rules. Consult the README for more information.

Changes

Firewall class manifests (Dan Carley)
Firewall and firewallchain persistence (Dan Carley)
(GH-134) Autorequire iptables related packages (Dan Carley)
Typo in #persist_iptables OS normalisation (Dan Carley)
Tests for #persist_iptables (Dan Carley)
(GH-129) Replace errant return in autoreq block (Dan Carley)

0.1.1 - 2012/2/28

This release primarily fixes changing parameters in 3.x

Changes

(GH-128) Change method_missing usage to define_method for 3.x compatibility
Update travis.yml gem specifications to actually test 2.6
Change source in Gemfile to use a specific URL for Ruby 2.0.0 compatibility

0.1.0 - 2012/2/24

This release is somewhat belated, so no summary as there are far too many changes this time around. Hopefully we won't fall this far behind again :-).

Changes

Add support for MARK target and set-mark property (Johan Huysmans)
Fix broken call to super for ruby-1.9.2 in munge (Ken Barber)
simple fix of the error message for allowed values of the jump property (Daniel Black)
Adding OSPF(v3) protocol to puppetlabs-firewall (Arnoud Vermeer)
Display multi-value: port, sport, dport and state command seperated (Daniel Black)
Require jump=>LOG for log params (Daniel Black)
Reject and document icmp => "any" (Dan Carley)
add firewallchain type and iptables_chain provider (Daniel Black)
Various fixes for firewallchain resource (Ken Barber)
Modify firewallchain name to be chain:table:protocol (Ken Barber)
Fix allvalidchain iteration (Ken Barber)
Firewall autorequire Firewallchains (Dan Carley)
Tests and docstring for chain autorequire (Dan Carley)
Fix README so setup instructions actually work (Ken Barber)
Support vlan interfaces (interface containing ".") (Johan Huysmans)
Add tests for VLAN support for iniface/outiface (Ken Barber)
Add the table when deleting rules (Johan Huysmans)
Fix tests since we are now prefixing -t)
Changed 'jump' to 'action', commands to lower case (Jason Short)
Support interface names containing "+" (Simon Deziel)
Fix for when iptables-save spews out "FATAL" errors (Sharif Nassar)
Fix for incorrect limit command arguments for ip6tables provider (Michael Hsu)
Document Util::Firewall.host_to_ip (Dan Carley)
Nullify addresses with zero prefixlen (Dan Carley)
Add support for --tcp-flags (Thomas Vander Stichele)
Make tcp_flags support a feature (Ken Barber)
OUTPUT is a valid chain for the mangle table (Adam Gibbins)
Enable travis-ci support (Ken Barber)
Convert an existing test to CIDR (Dan Carley)
Normalise iptables-save to CIDR (Dan Carley)
be clearer about what distributions we support (Ken Barber)
add gre protocol to list of acceptable protocols (Jason Hancock)
Added pkttype property (Ashley Penney)
Fix mark to not repeat rules with iptables 1.4.1+ (Sharif Nassar)
Stub iptables_version for now so tests run on non-Linux hosts (Ken Barber)
Stub iptables facts for set_mark tests (Dan Carley)
Update formatting of README to meet Puppet Labs best practices (Will Hopper)
Support for ICMP6 type code resolutions (Dan Carley)
Insert order hash included chains from different tables (Ken Barber)
rspec 2.11 compatibility (Jonathan Boyett)
Add missing class declaration in README (sfozz)
array_matching is contraindicated (Sharif Nassar)
Convert port Fixnum into strings (Sharif Nassar)
Update test framework to the modern age (Ken Barber)
working with ip6tables support (wuwx)
Remove gemfile.lock and add to gitignore (William Van Hevelingen)
Update travis and gemfile to be like stdlib travis files (William Van Hevelingen)
Add support for -m socket option (Ken Barber)
Add support for single --sport and --dport parsing (Ken Barber)
Fix tests for Ruby 1.9.3 from 3e13bf3 (Dan Carley)
Mock Resolv.getaddress in #host_to_ip (Dan Carley)
Update docs for source and dest - they are not arrays (Ken Barber)

0.0.4 - 2011/12/05

This release adds two new parameters, 'uid' and 'gid'. As a part of the owner module, these params allow you to specify a uid, username, gid, or group got a match:

firewall { '497 match uid':
  port => '123',
  proto => 'mangle',
  chain => 'OUTPUT',
  action => 'drop'
  uid => '123'
}

This release also adds value munging for the 'log_level', 'source', and 'destination' parameters. The 'source' and 'destination' now support hostnames:

firewall { '498 accept from puppetlabs.com':
  port => '123',
  proto => 'tcp',
  source => 'puppetlabs.com',
  action => 'accept'
}

The 'log_level' parameter now supports using log level names, such as 'warn', 'debug', and 'panic':

firewall { '499 logging':
  port => '123',
  proto => 'udp',
  log_level => 'debug',
  action => 'drop'
}

Additional changes include iptables and ip6tables version facts, general whitespace cleanup, and adding additional unit tests.

Changes

(#10957) add iptables_version and ip6tables_version facts
(#11093) Improve log_level property so it converts names to numbers
(#10723) Munge hostnames and IPs to IPs with CIDR
(#10718) Add owner-match support
(#10997) Add fixtures for ipencap
(#11034) Whitespace cleanup
(#10690) add port property support to ip6tables

0.0.3 - 2011/11/12

This release introduces a new parameter 'port' which allows you to set both source and destination ports for a match:

firewall { "500 allow NTP requests":
  port => "123",
  proto => "udp",
  action => "accept",
}

We also have the limit parameter finally working:

firewall { "500 limit HTTP requests":
  dport => 80,
  proto => tcp,
  limit => "60/sec",
  burst => 30,
  action => accept,
}

State ordering has been fixed now, and more characters are allowed in the namevar:

Alphabetical
Numbers
Punctuation
Whitespace

Changes

(#10693) Ensure -m limit is added for iptables when using 'limit' param
(#10690) Create new port property
(#10700) allow additional characters in comment string
(#9082) Sort iptables --state option values internally to keep it consistent across runs
(#10324) Remove extraneous whitespace from iptables rule line in spec tests

0.0.2 - 2011/10/26

This is largely a maintanence and cleanup release, but includes the ability to specify ranges of ports in the sport/dport parameter:

firewall { "500 allow port range":
  dport => ["3000-3030","5000-5050"],
  sport => ["1024-65535"],
  action => "accept",
}

Changes

(#10295) Work around bug #4248 whereby the puppet/util paths are not being loaded correctly on the puppetmaster
(#10002) Change to dport and sport to handle ranges, and fix handling of name to name to port
(#10263) Fix tests on Puppet 2.6.x
(#10163) Cleanup some of the inline documentation and README file to align with general forge usage

0.0.1 - 2011/10/18

Initial release.

Changes

(#9362) Create action property and perform transformation for accept, drop, reject value for iptables jump parameter
(#10088) Provide a customised version of CONTRIBUTING.md
(#10026) Re-arrange provider and type spec files to align with Puppet
(#10026) Add aliases for test,specs,tests to Rakefile and provide -T as default
(#9439) fix parsing and deleting existing rules
(#9583) Fix provider detection for gentoo and unsupported linuxes for the iptables provider
(#9576) Stub provider so it works properly outside of Linux
(#9576) Align spec framework with Puppet core
and lots of other earlier development tasks ...

Puppet Firewall Module - Puppet module for managing Firewalls

Copyright (C) 2011-2013 Puppet Labs, Inc.
Copyright (C) 2011 Jonathan Boyett
Copyright (C) 2011 Media Temple, Inc.

Some of the iptables code was taken from puppet-iptables which was:

Copyright (C) 2011 Bob.sh Limited
Copyright (C) 2008 Camptocamp Association
Copyright (C) 2007 Dmitri Priimak

Puppet Labs can be contacted at: info@puppetlabs.com

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Modules

Discover

Contribute

Resources

About Forge

Getting Started

firewall

Version information

Start using this module

Documentation

puppetlabs-firewall module

User Guide

Overview

Disclaimer

Downloading

Installation

Recommended Setup

Examples

Further documentation

Bugs

Developer Guide

Contributing

Testing

Types in this module release

firewallchain

firewall

puppetlabs-firewall changelog

0.2.0 - 2012/3/3

Changes

0.1.1 - 2012/2/28

Changes

0.1.0 - 2012/2/24

Changes

0.0.4 - 2011/12/05

Changes

0.0.3 - 2011/11/12

Changes

0.0.2 - 2011/10/26

Changes

0.0.1 - 2011/10/18

Changes