Module puppetlabs/firewall
| Download |
|
Module description
This type provides the capability to manage firewall rules within puppet.
Current support includes:
- iptables
- ip6tables
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.
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',
}
You can make firewall rules persistent with the following iptables example:
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"]
}
If you wish to ensure any reject rules are executed last, try using stages. The following example shows the creation of a class which is where your last rules should run, this however should belong in a puppet module.
class my_fw::drop {
iptables { "999 drop all":
action => "drop"
}
}
stage { pre: before => Stage[main] }
stage { post: require => Stage[main] }
class { "my_fw::drop": stage => "post" }
By placing the ‘my_fw::drop’ class in the post stage it will always be inserted last thereby avoiding locking you out before the accept rules are inserted.
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 in the Puppetlabs Redmine project:
Release notes for version 0.0.4
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
Types
firewall
Description
This type provides the capability to manage firewall rules within puppet.
Parameters
- 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. Values can match `/^\d+[[:alpha:][:digit:][:punct:][:space:]]+$/`.
- line
Read-only property for caching the rule line.
Properties
- ensure
Manage the state of this rule. The default action is *present*. Valid values are `present`, `absent`.
- 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*). Valid values are `accept`, `reject`, `drop`.
- source
An array of source addresses. For example: source => '192.168.2.0/24' The source can also be an IPv6 address if your provider supports it.
- destination
An array of destination addresses to match. For example: destination => '192.168.1.0/24' The destination 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.</ending_number></start_number>
- 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.</ending_number></start_number>
- 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.</ending_number></start_number>
- proto
The specific protocol to match for this rule. By default this is *tcp*. Valid values are `tcp`, `udp`, `icmp`, `ipv6-icmp`, `esp`, `ah`, `vrrp`, `igmp`, `ipencap`, `all`.
- 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'. Values can match `/^[a-zA-Z0-9\-_]+$/`. Requires features iptables.
- table
Table to use. Can be one of: * nat * mangle * filter * raw * rawpost By default the setting is 'filter'. Valid values are `nat`, `mangle`, `filter`, `raw`, `rawpost`. Requires features iptables.
- jump
The value for the iptables --jump parameter. Normal values are: * QUEUE * RETURN * DNAT * SNAT * LOG * MASQUERADE * REDIRECT 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. Requires features iptables.
- iniface
Input interface to filter on. Values can match `/^[a-zA-Z0-9\-_]+$/`. Requires features interface_match.
- outiface
Output interface to filter on. Values can match `/^[a-zA-Z0-9\-_]+$/`. Requires features interface_match.
- tosource
When using jump => "SNAT" you can specify the new source address using this parameter. Requires features snat.
- todest
When using jump => "DNAT" you can specify the new destination address using this paramter. Requires features dnat.
- toports
For DNAT this is the port that will replace the destination port. Requires features dnat.
- reject
When combined with jump => "REJECT" you can specify a different icmp response to be sent back to the packet sender. Requires features reject_type.
- log_level
When combined with jump => "LOG" specifies the system log level to log to. Requires features log_level.
- log_prefix
When combined with jump => "LOG" specifies the log prefix to use when logging. Requires features log_prefix.
- icmp
When matching ICMP packets, this is the type of ICMP packet to match. Requires features icmp_match.
- state
Matches a packet based on its state in the firewall stateful inspection table. Values can be: * INVALID * ESTABLISHED * NEW * RELATED Valid values are `INVALID`, `ESTABLISHED`, `NEW`, `RELATED`. Requires features state_match.
- 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'." Requires features rate_limiting.
- burst
Rate limiting burst value (per second) before limit checks apply. Values can match `/^\d+$/`. Requires features rate_limiting.
- uid
UID or Username owner matching rule. Accepts a string argument only, as iptables does not accept multiple uid in a single statement. Requires features owner.
- gid
GID or Group owner matching rule. Accepts a string argument only, as iptables does not accept multiple gid in a single statement. Requires features owner.
Providers
- ip6tables
Ip6tables type provider Required binaries:
/sbin/ip6tables,/sbin/ip6tables-save. Supported features:dnat,icmp_match,interface_match,iptables,log_level,log_prefix,owner,rate_limiting,reject_type,snat,state_match.
- iptables
Iptables type provider Required binaries:
/sbin/iptables,/sbin/iptables-save. Default forkernel==linux. Supported features:dnat,icmp_match,interface_match,iptables,log_level,log_prefix,owner,rate_limiting,reject_type,snat,state_match.