Version information
This version is compatible with:
- Puppet Enterprise 3.2.x
- Puppet 3.x
- , , , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'puppetlabs-firewall', '1.0.2'
Learn more about managing modules with a PuppetfileDocumentation
#firewall
####Table of Contents
- Overview - What is the Firewall module?
- Module Description - What does the module do?
- Setup - The basics of getting started with Firewall
- Usage - Configuration and customization options
- Reference - An under-the-hood peek at what the module is doing
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
##Overview
The Firewall module lets you manage firewall rules with Puppet.
##Module Description
PuppetLabs' Firewall introduces the resource firewall
, which is used to manage and configure firewall rules from within the Puppet DSL. This module offers support for iptables, ip6tables, and ebtables.
The module also introduces the resource firewallchain
, which allows you to manage chains or firewall lists. At the moment, only iptables and ip6tables chains are supported.
##Setup
###What Firewall affects:
- every node running a firewall
- system's firewall settings
- connection settings for managed nodes
- unmanaged resources (get purged)
- site.pp
###Setup Requirements
Firewall uses Ruby-based providers, so you must have pluginsync enabled.
###Beginning with Firewall
To begin, you need to provide some initial top-scope configuration to ensure your firewall configurations are ordered properly and you do not lock yourself out of your box or lose any configuration.
Persistence of rules between reboots is handled automatically, although there are known issues with ip6tables on older Debian/Ubuntu, as well as known issues with ebtables.
In your site.pp
(or some similarly top-scope file), set up a metatype to 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
}
Next, set up the default parameters for all of the firewall rules you will be establishing later. These defaults will ensure that the pre and post classes (you will be setting up in just a moment) are run in the correct order to avoid 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', 'my_fw::post']: }
Finally, you should include the firewall
class to ensure the correct packages are installed.
class { 'firewall': }
Now to create the my_fw::pre
and my_fw::post
classes. Firewall acts on your running firewall, making immediate changes as the catalog executes. Defining default pre and post rules allows you provide global defaults for your hosts before and after any custom rules; it is also required to avoid locking yourself out of your own boxes when Puppet runs. This approach employs a whitelist setup, so you can define what rules you want and everything else is ignored rather than removed.
The pre
class should be located in my_fw/manifests/pre.pp
and should contain any default rules to be applied first.
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',
ctstate => ['RELATED', 'ESTABLISHED'],
action => 'accept',
}
}
The rules in pre
should allow basic networking (such as ICMP and TCP), as well as ensure that existing connections are not closed.
The post
class should be located in my_fw/manifests/post.pp
and include any default rules to be applied last.
class my_fw::post {
firewall { '999 drop all':
proto => 'all',
action => 'drop',
before => undef,
}
}
To put it all together: the require
parameter in Firewall {}
ensures my_fw::pre
is run before any other rules and the before
parameter ensures my_fw::post
is run after any other rules. So the run order is:
- run the rules in
my_fw::pre
- run your rules (defined in code)
- run the rules in
my_fw::post
###Upgrading
####Upgrading from version 0.2.0 and newer
Upgrade the module with the puppet module tool as normal:
puppet module upgrade puppetlabs/firewall
####Upgrading from version 0.1.1 and older
Start by upgrading the module using the puppet module tool:
puppet module upgrade puppetlabs/firewall
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
}
With the latest version, we now have in-built persistence, so this is no longer needed. However, you will still need some basic setup to define pre & post rules.
resources { "firewall":
purge => true
}
Firewall {
before => Class['my_fw::post'],
require => Class['my_fw::pre'],
}
class { ['my_fw::pre', 'my_fw::post']: }
class { 'firewall': }
Consult the the documentation below for more details around the classes my_fw::pre
and my_fw::post
.
##Usage
There are two kinds of firewall rules you can use with Firewall: default rules and application-specific rules. Default rules apply to general firewall settings, whereas application-specific rules manage firewall settings of a specific application, node, etc.
All rules employ a numbering system in the resource's title that is used for ordering. When titling your rules, make sure you prefix the rule with a number.
000 this runs first
999 this runs last
###Default rules
You can place default rules in either my_fw::pre
or my_fw::post
, depending on when you would like them to run. Rules placed in the pre
class will run first, rules in the post
class, last.
Depending on the provider, the title of the rule can be stored using the comment feature of the underlying firewall subsystem. Values can match /^\d+[[:alpha:][:digit:][:punct:][:space:]]+$/
.
####Examples of default rules
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",
}
###Application-specific rules
Puppet doesn't care where you define rules, and this means that you can place your firewall resources as close to the applications and services that you manage as you wish. If you use the roles and profiles pattern then it would make sense to create your firewall rules in the profiles, so that they remain close to the services managed by the profile.
An example of this might be:
class profile::apache {
include apache
apache::vhost { 'mysite': ensure => present }
firewall { '100 allow http and https access':
port => [80, 443],
proto => tcp,
action => accept,
}
}
However, if you're not using that pattern then you can place them directly into the individual module that manages a service, such as:
class apache {
firewall { '100 allow http and https access':
port => [80, 443],
proto => tcp,
action => accept,
}
# ... the rest of your code ...
}
This means if someone includes either the profile:
include profile::apache
Or the module, if you're not using roles and profiles:
include ::apache
Then they would automatically get appropriate firewall rules.
###Other rules
You can also apply firewall rules to specific nodes. Usually, you will want to put the firewall rule in another class and apply that class to a node. But you can apply a rule to a node.
node 'foo.bar.com' {
firewall { '111 open port 111':
dport => 111
}
}
You can also do more complex things with the firewall
resource. Here we are doing some NAT configuration.
firewall { '100 snat for network foo2':
chain => 'POSTROUTING',
jump => 'MASQUERADE',
proto => 'all',
outiface => "eth0",
source => '10.1.2.0/24',
table => 'nat',
}
In the below example, we are creating a new chain and forwarding any port 5000 access to it.
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,
}
###Additional Information
You can access the inline documentation:
puppet describe firewall
Or
puppet doc -r type
(and search for firewall)
##Reference
Classes:
Types:
Facts:
###Class: firewall
This class is provided to do the basic setup tasks required for using the firewall resources.
At the moment this takes care of:
- iptables-persistent package installation
You should include the class for nodes that need to use the resources in this module. For example
class { 'firewall': }
####ensure
Indicates the state of iptables
on your system, allowing you to disable iptables
if desired.
Can either be running
or stopped
. Default to running
.
###Type: firewall
This type provides the capability to manage firewall rules within puppet.
For more documentation on the type, access the 'Types' tab on the Puppet Labs Forge:
http://forge.puppetlabs.com/puppetlabs/firewall#types
###Type:: firewallchain
This type provides the capability to manage rule chains for firewalls.
For more documentation on the type, access the 'Types' tab on the Puppet Labs Forge:
http://forge.puppetlabs.com/puppetlabs/firewall#types
###Fact: ip6tables_version
The module provides a Facter fact that can be used to determine what the default version of ip6tables is for your operating system/distribution.
###Fact: iptables_version
The module provides a Facter fact that can be used to determine what the default version of iptables is for your operating system/distribution.
###Fact: iptables_persistent_version
Retrieves the version of iptables-persistent from your OS. This is a Debian/Ubuntu specific fact.
##Limitations
###SLES
The socket
parameter is not supported on SLES. In this release it will cause
the catalog to fail with iptables failures, rather than correctly warn you that
the features are unusable.
###Oracle Enterprise Linux
The socket
and owner
parameters are unsupported on Oracle Enterprise Linux
when the "Unbreakable" kernel is used. These may function correctly when using
the stock RedHat kernel instead. Declaring either of these parameters on an
unsupported system will result in iptable rules failing to apply.
###Other
Bugs can be reported using Github Issues:
http://github.com/puppetlabs/puppetlabs-firewall/issues
##Development
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
You can read the complete module contribution guide on the Puppet Labs wiki.
For this particular module, please also 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 technologies, know how to code, and wish to contribute to this project, we would welcome the help.
###Testing
Make sure you have:
- rake
- bundler
Install the necessary gems:
bundle install
And run the tests from the root of the source code:
rake test
If you have a copy of Vagrant 1.1.0 you can also run the system tests:
RSPEC_SET=debian-606-x64 rake spec:system
RSPEC_SET=centos-58-x64 rake spec:system
Note: system testing is fairly alpha at this point, your mileage may vary.
Types in this module release
2014-03-04 Supported Release 1.0.2
###Summary
This is a supported release. This release removes a testing symlink that can cause trouble on systems where /var is on a seperate filesystem from the modulepath.
####Features ####Bugfixes ####Known Bugs
- For Oracle, the
owner
andsocket
parameters require a workaround to function. Please see the Limitations section of the README.
Supported release - 2014-03-04 1.0.1
####Summary
An important bugfix was made to the offset calculation for unmanaged rules to handle rules with 9000+ in the name.
####Features
####Bugfixes
- Offset calculations assumed unmanaged rules were numbered 9000+.
- Gracefully fail to manage ip6tables on iptables 1.3.x
####Known Bugs
- For Oracle, the
owner
andsocket
parameters require a workaround to function. Please see the Limitations section of the README.
1.0.0 - 2014-02-11
No changes, just renumbering to 1.0.0.
0.5.0 - 2014-02-10
Summary:
This is a bigger release that brings in "recent" connection limiting (think "port knocking"), firewall chain purging on a per-chain/per-table basis, and support for a few other use cases. This release also fixes a major bug which could cause modifications to the wrong rules when unmanaged rules are present.
New Features:
- Add "recent" limiting via parameters
rdest
,reap
,recent
,rhitcount
,rname
,rseconds
,rsource
, andrttl
- Add negation support for source and destination
- Add per-chain/table purging support to
firewallchain
- IPv4 specific
- Add random port forwarding support
- Add ipsec policy matching via
ipsec_dir
andipsec_policy
- IPv6 specific
- Add support for hop limiting via
hop_limit
parameter - Add fragmentation matchers via
ishasmorefrags
,islastfrag
, andisfirstfrag
- Add support for conntrack stateful firewall matching via
ctstate
- Add support for hop limiting via
Bugfixes:
- Boolean fixups allowing false values
- Better detection of unmanaged rules
- Fix multiport rule detection
- Fix sport/dport rule detection
- Make INPUT, OUTPUT, and FORWARD not autorequired for firewall chain filter
- Allow INPUT with the nat table
- Fix
src_range
&dst_range
order detection - Documentation clarifications
- Fixes to spec tests
0.4.2 - 2013-09-10
Another attempt to fix the packaging issue. We think we understand exactly what is failing and this should work properly for the first time.
0.4.1 - 2013-08-09
Bugfix release to fix a packaging issue that may have caused puppet module install commands to fail.
0.4.0 - 2013-07-11
This release adds support for address type, src/dest ip ranges, and adds additional testing and bugfixes.
Features
- Add
src_type
anddst_type
attributes (Nick Stenning) - Add
src_range
anddst_range
attributes (Lei Zhang) - Add SL and SLC operatingsystems as supported (Steve Traylen)
Bugfixes
- Fix parser for bursts other than 5 (Chris Rutter)
- Fix parser for -f in --comment (Georg Koester)
- Add doc headers to class files (Dan Carley)
- Fix lint warnings/errors (Wolf Noble)
0.3.1 - 2013/6/10
This minor release provides some bugfixes and additional tests.
Changes
- Update tests for rspec-system-puppet 2 (Ken Barber)
- Update rspec-system tests for rspec-system-puppet 1.5 (Ken Barber)
- Ensure all services have 'hasstatus => true' for Puppet 2.6 (Ken Barber)
- Accept pre-existing rule with invalid name (Joe Julian)
- Swap log_prefix and log_level order to match the way it's saved (Ken Barber)
- Fix log test to replicate bug #182 (Ken Barber)
- Split argments while maintaining quoted strings (Joe Julian)
- Add more log param tests (Ken Barber)
- Add extra tests for logging parameters (Ken Barber)
- Clarify OS support (Ken Barber)
0.3.0 - 2013/4/25
This release introduces support for Arch Linux and extends support for Fedora 15 and up. There are also lots of bugs fixed and improved testing to prevent regressions.
Changes
- Fix error reporting for insane hostnames (Tomas Doran)
- Support systemd on Fedora 15 and up (Eduardo Gutierrez)
- Move examples to docs (Ken Barber)
- Add support for Arch Linux platform (Ingmar Steen)
- Add match rule for fragments (Georg Koester)
- Fix boolean rules being recognized as changed (Georg Koester)
- Same rules now get deleted (Anastasis Andronidis)
- Socket params test (Ken Barber)
- Ensure parameter can disable firewall (Marc Tardif)
0.2.1 - 2012/3/13
This maintenance release introduces the new README layout, and fixes a bug with iptables_persistent_version.
Changes
- (GH-139) Throw away STDERR from dpkg-query in Fact
- Update README to be consistent with module documentation template
- Fix failing spec tests due to dpkg change in iptables_persistent_version
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.