Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 812 lines (538 sloc) 36.394 kb
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
1 #firewall
bff53bd @saysjonathan initial commit
saysjonathan authored
2
fa699cb @kbarber Update test framework to the modern age
kbarber authored
3 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-firewall.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-firewall)
4
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
5 ####Table of Contents
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
6
4def60a Updates to format to fit style guide.
Lauren authored
7 1. [Overview - What is the firewall module?](#overview)
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
8 2. [Module Description - What does the module do?](#module-description)
4def60a Updates to format to fit style guide.
Lauren authored
9 3. [Setup - The basics of getting started with firewall](#setup)
10 * [What firewall Affects](#what-firewall-affects)
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
11 * [Setup Requirements](#setup-requirements)
4def60a Updates to format to fit style guide.
Lauren authored
12 * [Beginning with firewall](#beginning-with-firewall)
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
13 * [Upgrading](#upgrading)
14 4. [Usage - Configuration and customization options](#usage)
15 * [Default rules - Setting up general configurations for all firewalls](#default-rules)
aecdb22 @MFredette Format fixes to firewall readme.
MFredette authored
16 * [Application-Specific Rules - Options for configuring and managing firewalls across applications](#application-specific-rules)
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
17 * [Additional Uses for the Firewall Module](#other-rules)
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
18 5. [Reference - An under-the-hood peek at what the module is doing](#reference)
19 6. [Limitations - OS compatibility, etc.](#limitations)
20 7. [Development - Guide for contributing to the module](#development)
21 * [Tests - Testing your configuration](#tests)
bff53bd @saysjonathan initial commit
saysjonathan authored
22
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
23 ##Overview
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
24
4def60a Updates to format to fit style guide.
Lauren authored
25 The firewall module lets you manage firewall rules with Puppet.
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
26
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
27 ##Module Description
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
28
4def60a Updates to format to fit style guide.
Lauren authored
29 PuppetLabs' firewall module introduces the `firewall` resource, which is used to manage and configure firewall rules from within the Puppet DSL. This module offers support for iptables and ip6tables. The module also introduces the `firewallchain` resource, which allows you to manage chains or firewall lists and ebtables for bridging support. At the moment, only iptables and ip6tables chains are supported.
bff53bd @saysjonathan initial commit
saysjonathan authored
30
4def60a Updates to format to fit style guide.
Lauren authored
31 The firewall module acts on your running firewall, making immediate changes as the catalog executes. Defining default pre and post rules allows you to provide global defaults for your hosts before and after any custom rules. Defining `pre` and `post` rules is also necessary to help you avoid locking yourself out of your own boxes when Puppet runs.
bff53bd @saysjonathan initial commit
saysjonathan authored
32
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
33 ##Setup
bff53bd @saysjonathan initial commit
saysjonathan authored
34
4def60a Updates to format to fit style guide.
Lauren authored
35 ###What firewall Affects
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
36
37 * Every node running a firewall
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
38 * Firewall settings in your system
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
39 * Connection settings for managed nodes
40 * Unmanaged resources (get purged)
bff53bd @saysjonathan initial commit
saysjonathan authored
41
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
42
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
43 ###Setup Requirements
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
44
4def60a Updates to format to fit style guide.
Lauren authored
45 Firewall uses Ruby-based providers, so you must enable [pluginsync](http://docs.puppetlabs.com/guides/plugins_in_modules.html#enabling-pluginsync).
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
46
4def60a Updates to format to fit style guide.
Lauren authored
47 ###Beginning with firewall
55a2299 @kbarber Added some more examples and README cleanup.
kbarber authored
48
4def60a Updates to format to fit style guide.
Lauren authored
49 In the following two sections, you create new classes and then create firewall rules related to those classes. These steps are optional but provide a framework for firewall rules, which is helpful if you’re just starting to create them.
f3a7e0c @kbarber (#10295) Work around bug #4248 whereby the puppet/util paths are not bei...
kbarber authored
50
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
51 If you already have rules in place, then you don’t need to do these two sections. However, be aware of the ordering of your firewall rules. The module will dynamically apply rules in the order they appear in the catalog, meaning a deny rule could be applied before the allow rules. This might mean the module hasn’t established some of the important connections, such as the connection to the Puppet master.
f3a7e0c @kbarber (#10295) Work around bug #4248 whereby the puppet/util paths are not bei...
kbarber authored
52
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
53 The following steps are designed to ensure that you keep your SSH and other connections, primarily your connection to your Puppet master. If you create the `pre` and `post` classes described in the first section, then you also need to create the rules described in the second section.
97a63a8 @kbarber Release 0.2.0
kbarber authored
54
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
55 ####Create the `my_fw::pre` and `my_fw::post` Classes
be6d30c @kbarber (#13216) Fix README so setup instructions actually work
kbarber authored
56
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
57 This approach employs a whitelist setup, so you can define what rules you want and everything else is ignored rather than removed.
0913456 @sfozz Add missing class declaration
sfozz authored
58
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
59 The code in this section does the following:
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
60
4def60a Updates to format to fit style guide.
Lauren authored
61 * The 'require' parameter in `firewall {}` ensures `my_fw::pre` is run before any other rules.
62 * In the `my_fw::post` class declaration, the 'before' parameter ensures `my_fw::post` is run after any other rules.
6b46c9d @MFredette Copy edited version.
MFredette authored
63
64 Therefore, the run order is:
0913456 @sfozz Add missing class declaration
sfozz authored
65
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
66 * The rules in `my_fw::pre`
67 * Your rules (defined in code)
68 * The rules in `my_fw::post`
0913456 @sfozz Add missing class declaration
sfozz authored
69
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
70 The rules in the `pre` and `post` classes are fairly general. These two classes ensure that you retain connectivity and that you drop unmatched packets appropriately. The rules you define in your manifests are likely specific to the applications you run.
be6d30c @kbarber (#13216) Fix README so setup instructions actually work
kbarber authored
71
4def60a Updates to format to fit style guide.
Lauren authored
72 1.) Add the `pre` class to my_fw/manifests/pre.pp. Your pre.pp file should contain any default rules to be applied first. The rules in this class should be added in the order you want them to run.2.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
73 ```puppet
74 class my_fw::pre {
75 Firewall {
76 require => undef,
77 }
be6d30c @kbarber (#13216) Fix README so setup instructions actually work
kbarber authored
78
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
79 # Default firewall rules
80 firewall { '000 accept all icmp':
81 proto => 'icmp',
82 action => 'accept',
83 }->
84 firewall { '001 accept all to lo interface':
85 proto => 'all',
86 iniface => 'lo',
87 action => 'accept',
88 }->
89 firewall { "002 reject local traffic not on loopback interface":
90 iniface => '! lo',
91 proto => 'all',
92 destination => '127.0.0.1/8',
93 action => 'reject',
94 }->
95 firewall { '003 accept related established rules':
96 proto => 'all',
97 state => ['RELATED', 'ESTABLISHED'],
98 action => 'accept',
6b46c9d @MFredette Copy edited version.
MFredette authored
99 }
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
100 }
101 ```
be6d30c @kbarber (#13216) Fix README so setup instructions actually work
kbarber authored
102
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
103 The rules in `pre` should allow basic networking (such as ICMP and TCP) and ensure that existing connections are not closed.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
104
4def60a Updates to format to fit style guide.
Lauren authored
105 2.) Add the `post` class to my_fw/manifests/post.pp and include any default rules to be applied last.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
106 ```puppet
107 class my_fw::post {
108 firewall { '999 drop all':
109 proto => 'all',
110 action => 'drop',
111 before => undef,
6b46c9d @MFredette Copy edited version.
MFredette authored
112 }
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
113 }
114 ```
be6d30c @kbarber (#13216) Fix README so setup instructions actually work
kbarber authored
115
ee78d8b @jpds README: Added example of firewallchain for drop policy on input.
jpds authored
116 Alternatively, the [firewallchain](#type-firewallchain) type can be used to set the default policy:
117
118 ```puppet
119 firewallchain { 'INPUT:filter:IPv4':
120 ensure => present,
121 policy => drop,
122 before => undef,
123 }
124 ```
125
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
126 ####Create Firewall Rules
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
127
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
128 The rules you create here are helpful if you don’t have any existing rules; they help you order your firewall configurations so you don’t lock yourself out of your box.
412620a @hunner Revert "Merge pull request #342 from mcanevet/feature/autorequire"
hunner authored
129
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
130 Rules are persisted automatically between reboots, although there are known issues with ip6tables on older Debian/Ubuntu distributions. There are also known issues with ebtables.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
131
4def60a Updates to format to fit style guide.
Lauren authored
132 1.) In site.pp or another top-scope file, add the following code to 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.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
133
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
134 **Note** - This only purges IPv4 rules.
135 ```puppet
749720b @mhaskel (MODULES-1866) Update documentation for purging firewall chains
mhaskel authored
136 resources { 'firewall':
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
137 purge => true
138 }
139 ```
749720b @mhaskel (MODULES-1866) Update documentation for purging firewall chains
mhaskel authored
140
141 To purge unmanaged firewall chains, also add:
142
143 ```puppet
144 resources { 'firewallchain':
145 purge => true
146 }
147 ```
5e8eaed @mhaskel purge clarifications
mhaskel authored
148 **Note** - If there are unmanaged rules in unmanaged chains it will take two Puppet runs before the firewall chain is purged. This is different than the `purge` parameter available in `firewallchain`.
749720b @mhaskel (MODULES-1866) Update documentation for purging firewall chains
mhaskel authored
149
4def60a Updates to format to fit style guide.
Lauren authored
150 2.) Use the following code to set up the default parameters for all of the firewall rules you will establish later. These defaults will ensure that the `pre` and `post` classes are run in the correct order to avoid locking you out of your box during the first Puppet run.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
151
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
152 ```puppet
153 Firewall {
154 before => Class['my_fw::post'],
155 require => Class['my_fw::pre'],
156 }
157 ```
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
158
4def60a Updates to format to fit style guide.
Lauren authored
159 3.) Then, declare the `my_fw::pre` and `my_fw::post` classes to satisfy dependencies. You can declare these classes using an External Node Classifier or the following code:
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
160
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
161 ```puppet
162 class { ['my_fw::pre', 'my_fw::post']: }
163 ```
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
164
4def60a Updates to format to fit style guide.
Lauren authored
165 4.) Include the `firewall` class to ensure the correct packages are installed.
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
166
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
167 ```puppet
168 class { 'firewall': }
169 ```
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
170
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
171 ###Upgrading
172
4def60a Updates to format to fit style guide.
Lauren authored
173 Use these steps if you already have a version of the firewall module installed.
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
174
6b46c9d @MFredette Copy edited version.
MFredette authored
175 ####From version 0.2.0 and more recent
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
176
177 Upgrade the module with the puppet module tool as normal:
178
179 puppet module upgrade puppetlabs/firewall
180
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
181 ##Usage
182
4def60a Updates to format to fit style guide.
Lauren authored
183 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 for a specific application, node, etc.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
184
4def60a Updates to format to fit style guide.
Lauren authored
185 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, for example, '000 accept all icmp requests'. _000_ runs first, _999_ runs last.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
186
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
187 ###Default Rules
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
188
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
189 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, and rules in the `post` class, last.
412620a @hunner Revert "Merge pull request #342 from mcanevet/feature/autorequire"
hunner authored
190
4def60a Updates to format to fit style guide.
Lauren authored
191 In iptables, the title of the rule is stored using the comment feature of the underlying firewall subsystem. Values must match '/^\d+[[:alpha:][:digit:][:punct:][:space:]]+$/'.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
192
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
193 ####Examples of Default Rules
55a2299 @kbarber Added some more examples and README cleanup.
kbarber authored
194
195 Basic accept ICMP request example:
196
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
197 ```puppet
198 firewall { "000 accept all icmp requests":
199 proto => "icmp",
200 action => "accept",
201 }
202 ```
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
203 Drop all:
55a2299 @kbarber Added some more examples and README cleanup.
kbarber authored
204
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
205 ```puppet
206 firewall { "999 drop all other requests":
207 action => "drop",
208 }
209 ```
88b4c00 @jpds README: Added an example of an IPv6-based rule.
jpds authored
210
211 #### Example of an IPv6 rule
212
213 IPv6 rules can be specified using the _ip6tables_ provider:
214
215 ```puppet
216 firewall { "006 Allow inbound SSH (v6)":
217 port => 22,
218 proto => tcp,
219 action => accept,
220 provider => 'ip6tables',
221 }
222 ```
223
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
224 ###Application-Specific Rules
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
225
fac1714 Rewrite this to make it clear the roles and profiles pattern would be
Ashley Penney authored
226 Puppet doesn't care where you define rules, and this means that you can place
227 your firewall resources as close to the applications and services that you
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
228 manage as you wish. If you use the [roles and profiles
fac1714 Rewrite this to make it clear the roles and profiles pattern would be
Ashley Penney authored
229 pattern](https://puppetlabs.com/learn/roles-profiles-introduction) then it
4def60a Updates to format to fit style guide.
Lauren authored
230 makes sense to create your firewall rules in the profiles, so they
fac1714 Rewrite this to make it clear the roles and profiles pattern would be
Ashley Penney authored
231 remain close to the services managed by the profile.
232
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
233 This is an example of firewall rules in a profile:
fac1714 Rewrite this to make it clear the roles and profiles pattern would be
Ashley Penney authored
234
235 ```puppet
236 class profile::apache {
237 include apache
238 apache::vhost { 'mysite': ensure => present }
239
240 firewall { '100 allow http and https access':
241 port => [80, 443],
242 proto => tcp,
243 action => accept,
244 }
245 }
246 ```
247
d5312a5 @hunner (MODULES-450) Enable rule inversion
hunner authored
248 ###Rule inversion
249 Firewall rules may be inverted by prefixing the value of a parameter by "! ". If the value is an array, then every item in the array must be prefixed as iptables does not understand inverting a single value.
250
b6e58ba @hesco MODULES-1469 MODULES-1470 Support alias (eth0:0), negation for iniface, ...
hesco authored
251 Parameters that understand inversion are: connmark, ctstate, destination, dport, dst\_range, dst\_type, iniface, outiface, port, proto, source, sport, src\_range, src\_type, and state.
d5312a5 @hunner (MODULES-450) Enable rule inversion
hunner authored
252
253 Examples:
254
255 ```puppet
256 firewall { '001 disallow esp protocol':
257 action => 'accept',
258 proto => '! esp',
259 }
260 firewall { '002 drop NEW external website packets with FIN/RST/ACK set and SYN unset':
261 chain => 'INPUT',
262 state => 'NEW',
263 action => 'drop',
264 proto => 'tcp',
265 sport => ['! http', '! 443'],
266 source => '! 10.0.0.0/8',
267 tcp_flags => '! FIN,SYN,RST,ACK SYN',
268 }
269 ```
fac1714 Rewrite this to make it clear the roles and profiles pattern would be
Ashley Penney authored
270
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
271 ###Additional Uses for the Firewall Module
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
272
6b46c9d @MFredette Copy edited version.
MFredette authored
273 You can 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. Apply a rule to a node as follows:
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
274
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
275 ```puppet
276 node 'some.node.com' {
277 firewall { '111 open port 111':
278 dport => 111
279 }
280 }
281 ```
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
282
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
283 You can also do more complex things with the `firewall` resource. This example sets up static NAT for the source network 10.1.2.0/24:
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
284 ```puppet
285 firewall { '100 snat for network foo2':
286 chain => 'POSTROUTING',
287 jump => 'MASQUERADE',
288 proto => 'all',
289 outiface => "eth0",
290 source => '10.1.2.0/24',
291 table => 'nat',
292 }
293 ```
64fd558 @kbarber Small example for MASQUERADE.
kbarber authored
294
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
295 The following example creates a new chain and forwards any port 5000 access to it.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
296 ```puppet
297 firewall { '100 forward to MY_CHAIN':
298 chain => 'INPUT',
299 jump => 'MY_CHAIN',
300 }
301 # The namevar here is in the format chain_name:table:protocol
302 firewallchain { 'MY_CHAIN:filter:IPv4':
303 ensure => present,
304 }
305 firewall { '100 my rule':
306 chain => 'MY_CHAIN',
307 action => 'accept',
308 proto => 'tcp',
309 dport => 5000,
310 }
311 ```
9715882 @kbarber (#10162) Various fixes for firewallchain resource
kbarber authored
312
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
313 ###Additional Information
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
314
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
315 Access the inline documentation:
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
316
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
317 puppet describe firewall
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
318
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
319 Or
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
320
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
321 puppet doc -r type
322 (and search for firewall)
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
323
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
324 ##Reference
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
325
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
326 Classes:
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
327
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
328 * [firewall](#class-firewall)
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
329
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
330 Types:
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
331
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
332 * [firewall](#type-firewall)
333 * [firewallchain](#type-firewallchain)
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
334
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
335 Facts:
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
336
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
337 * [ip6tables_version](#fact-ip6tablesversion)
338 * [iptables_version](#fact-iptablesversion)
339 * [iptables_persistent_version](#fact-iptablespersistentversion)
340
b08e312 @kbarber Document ensure class parameter
kbarber authored
341 ###Class: firewall
b4cec3f @kbarber Applied docs to explain putting rejects in post stage (#4). Plus some re...
kbarber authored
342
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
343 Performs the basic setup tasks required for using the firewall resources.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
344
345 At the moment this takes care of:
346
347 * iptables-persistent package installation
348
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
349 Include the `firewall` class for nodes that need to use the resources in this module:
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
350
412620a @hunner Revert "Merge pull request #342 from mcanevet/feature/autorequire"
hunner authored
351 class { 'firewall': }
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
352
4def60a Updates to format to fit style guide.
Lauren authored
353 ####ensure
b08e312 @kbarber Document ensure class parameter
kbarber authored
354
4def60a Updates to format to fit style guide.
Lauren authored
355 Parameter that controls the state of the iptables service on your system, allowing you to disable iptables if you want.
b08e312 @kbarber Document ensure class parameter
kbarber authored
356
4def60a Updates to format to fit style guide.
Lauren authored
357 `ensure` can either be 'running' or 'stopped'. Default to 'running'.
b08e312 @kbarber Document ensure class parameter
kbarber authored
358
4def60a Updates to format to fit style guide.
Lauren authored
359 ####package
f9a2db9 @mhaskel MODULES-1309 - Make package and service names configurable
mhaskel authored
360
361 Specify the platform-specific package(s) to install. Defaults defined in `firewall::params`.
362
4def60a Updates to format to fit style guide.
Lauren authored
363 ####service
f9a2db9 @mhaskel MODULES-1309 - Make package and service names configurable
mhaskel authored
364
365 Specify the platform-specific service(s) to start or stop. Defaults defined in `firewall::params`.
366
b08e312 @kbarber Document ensure class parameter
kbarber authored
367 ###Type: firewall
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
368
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
369 This type enables you to manage firewall rules within Puppet.
370
4def60a Updates to format to fit style guide.
Lauren authored
371 ####Providers
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
372 **Note:** Not all features are available with all providers.
373
374 * `ip6tables`: Ip6tables type provider
375 * Required binaries: `ip6tables-save`, `ip6tables`.
e0d8b64 @mhaskel README updates
mhaskel authored
376 * Supported features: `address_type`, `connection_limiting`, `dnat`, `hop_limiting`, `icmp_match`, `interface_match`, `iprange`, `ipsec_dir`, `ipsec_policy`, `ipset`, `iptables`, `isfirstfrag`, `ishasmorefrags`, `islastfrag`, `log_level`, `log_prefix`, `mark`, `mask`, `owner`, `pkttype`, `rate_limiting`, `recent_limiting`, `reject_type`, `snat`, `socket`, `state_match`, `tcp_flags`.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
377
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
378 * `iptables`: Iptables type provider
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
379 * Required binaries: `iptables-save`, `iptables`.
380 * Default for `kernel` == `linux`.
e0d8b64 @mhaskel README updates
mhaskel authored
381 * Supported features: `address_type`, `connection_limiting`, `dnat`, `icmp_match`, `interface_match`, `iprange`, `ipsec_dir`, `ipsec_policy`, `ipset`, `iptables`, `isfragment`, `log_level`, `log_prefix`, `mark`, `mask`, `netmap`, `owner`, `pkttype`, `rate_limiting`, `recent_limiting`, `reject_type`, `snat`, `socket`, `state_match`, `tcp_flags`.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
382
383 **Autorequires:**
384
385 If Puppet is managing the iptables or ip6tables chains specified in the `chain` or `jump` parameters, the firewall resource will autorequire those firewallchain resources.
386
387 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.
388
389 #### Features
390
391 * `address_type`: The ability to match on source or destination address type.
392
393 * `connection_limiting`: Connection limiting features.
394
395 * `dnat`: Destination NATing.
396
397 * `hop_limiting`: Hop limiting features.
398
399 * `icmp_match`: The ability to match ICMP types.
400
401 * `interface_match`: Interface matching.
402
403 * `iprange`: The ability to match on source or destination IP range.
404
405 * `ipsec_dir`: The ability to match IPsec policy direction.
406
407 * `ipsec_policy`: The ability to match IPsec policy.
408
409 * `iptables`: The provider provides iptables features.
410
411 * `isfirstfrag`: The ability to match the first fragment of a fragmented ipv6 packet.
412
413 * `isfragment`: The ability to match fragments.
414
415 * `ishasmorefrags`: The ability to match a non-last fragment of a fragmented ipv6 packet.
416
417 * `islastfrag`: The ability to match the last fragment of an ipv6 packet.
418
419 * `log_level`: The ability to control the log level.
420
421 * `log_prefix`: The ability to add prefixes to log messages.
422
423 * `mark`: The ability to match or set the netfilter mark value associated with the packet.
424
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
425 * `mask`: The ability to match recent rules based on the ipv4 mask.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
426
427 * `owner`: The ability to match owners.
428
429 * `pkttype`: The ability to match a packet type.
430
431 * `rate_limiting`: Rate limiting features.
432
433 * `recent_limiting`: The netfilter recent module.
434
435 * `reject_type`: The ability to control reject messages.
436
437 * `snat`: Source NATing.
438
439 * `socket`: The ability to match open sockets.
440
441 * `state_match`: The ability to match stateful firewall states.
442
443 * `tcp_flags`: The ability to match on particular TCP flag settings.
444
f45fa3b @nemski Add netmap feature and acceptance tests
nemski authored
445 * `netmap`: The ability to map entire subnets via source or destination nat rules.
446
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
447 #### Parameters
448
449 * `action`: This is the action to perform on a match. Valid values for this action are:
450 * 'accept': The packet is accepted.
451 * 'reject': The packet is rejected with a suitable ICMP response.
452 * 'drop': The packet is dropped.
453
454 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`).
455
456 * `burst`: Rate limiting burst value (per second) before limit checks apply. Values must match '/^\d+$/'. Requires the `rate_limiting` feature.
457
458 * `chain`: Name of the chain to use. You can provide a user-based chain or use one of the following built-in chains:'INPUT','FORWARD','OUTPUT','PREROUTING', or 'POSTROUTING'. The default value is 'INPUT'. Values must match '/^[a-zA-Z0-9\-_]+$/'. Requires the `iptables` feature.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
459
07667a0 MODULES-1636: add iptables --checksum-fill support
Marc Olzheim authored
460 * `checksum_fill`: When using a `jump` value of 'CHECKSUM' this boolean will make sure that a checksum is calculated and filled in a packet that lacks a checksum. Valid values are true or false. Requires the `iptables` feature.
461
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
462 * `connlimit_above`: Connection limiting value for matched connections above n. Values must match '/^\d+$/'. Requires the `connection_limiting` feature.
463
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
464 * `connlimit_mask`: Connection limiting by subnet mask for matched connections. Apply a subnet mask of /0 to /32 for IPv4, and a subnet mask of /0 to /128 for IPv6. Values must match '/^\d+$/'. Requires the `connection_limiting` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
465
466 * `connmark`: Match the Netfilter mark value associated with the packet. Accepts values `mark/mask` or `mark`. These will be converted to hex if they are not hex already. Requires the `mark` feature.
467
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
468 * `ctstate`: Matches a packet based on its state in the firewall stateful inspection table, using the conntrack module. Valid values are: 'INVALID', 'ESTABLISHED', 'NEW', 'RELATED'. Requires the `state_match` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
469
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
470 * `destination`: The destination address to match. For example: `destination => '192.168.1.0/24'`. You can also negate a mask by putting ! in front. For example: `destination => '! 192.168.2.0/24'`. The destination can also be an IPv6 address if your provider supports it.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
471
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
472 For some firewall providers you can pass a range of ports in the format: 'start number-end number'. For example, '1-1024' would cover ports 1 to 1024.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
473
474 * `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-end number'. For example, '1-1024' would cover ports 1 to 1024.
475
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
476 * `dst_range`: The destination IP range. For example: `dst_range => '192.168.1.1-192.168.1.10'`.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
477
5efdee6 @mhaskel MODULES-1612 - sync src_range and dst_range
mhaskel authored
478 The destination IP range is must in 'IP1-IP2' format. Values in the range must be valid IPv4 or IPv6 addresses. Requires the `iprange` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
479
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
480 * `dst_type`: The destination address type. For example: `dst_type => 'LOCAL'`.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
481
482 Valid values are:
483
484 * 'UNSPEC': an unspecified address
485 * 'UNICAST': a unicast address
486 * 'LOCAL': a local address
487 * 'BROADCAST': a broadcast address
488 * 'ANYCAST': an anycast packet
489 * 'MULTICAST': a multicast address
490 * 'BLACKHOLE': a blackhole address
491 * 'UNREACHABLE': an unreachable address
492 * 'PROHIBIT': a prohibited address
493 * 'THROW': an unroutable address
494 * 'XRESOLVE: an unresolvable address
495
496 Requires the `address_type` feature.
497
498 * `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'. The default is 'present'.
499
500 * `gid`: GID or Group owner matching rule. Accepts a string argument only, as iptables does not accept multiple gid in a single statement. Requires the `owner` feature.
501
502 * `hop_limit`: Hop limiting value for matched packets. Values must match '/^\d+$/'. Requires the `hop_limiting` feature.
503
504 * `icmp`: When matching ICMP packets, this indicates the type of ICMP packet to match. A value of 'any' is not supported. To match any type of ICMP packet, the parameter should be omitted or undefined. Requires the `icmp_match` feature.
505
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
506 * `iniface`: Input interface to filter on. Values must match '/^!?\s?[a-zA-Z0-9\-\._\+\:]+$/'. Requires the `interface_match` feature. Supports interface alias (eth0:0) and negation.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
507
508 * `ipsec_dir`: Sets the ipsec policy direction. Valid values are 'in', 'out'. Requires the `ipsec_dir` feature.
509
510 * `ipsec_policy`: Sets the ipsec policy type. Valid values are 'none', 'ipsec'. Requires the `ipsec_policy` feature.
511
4def60a Updates to format to fit style guide.
Lauren authored
512 * `ipset`: Matches IP sets. Value must be 'ipset_name (src|dst|src,dst)' and can be negated by putting ! in front. Requires ipset kernel module.
e7f9a38 @vzctl add more ipset documentation
vzctl authored
513
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
514 * `isfirstfrag`: If true, matches when the packet is the first fragment of a fragmented ipv6 packet. Cannot be negated. Supported by ipv6 only. Valid values are 'true', 'false'. Requires the `isfirstfrag` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
515
516 * `isfragment`: If 'true', matches when the packet is a tcp fragment of a fragmented packet. Supported by iptables only. Valid values are 'true', 'false'. Requires features `isfragment`.
517
518 * `ishasmorefrags`: If 'true', matches when the packet has the 'more fragments' bit set. Supported by ipv6 only. Valid values are 'true', 'false'. Requires the `ishasmorefrags` feature.
519
520 * `islastfrag`: If true, matches when the packet is the last fragment of a fragmented ipv6 packet. Supported by ipv6 only. Valid values are 'true', 'false'. Requires the `islastfrag`.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
521
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
522 * `jump`: The value for the iptables `--jump` parameter. Any valid chain name is allowed, but normal values are: 'QUEUE', 'RETURN', 'DNAT', 'SNAT', 'LOG', 'MASQUERADE', 'REDIRECT', 'MARK'.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
523
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
524 For the values 'ACCEPT', 'DROP', and 'REJECT', you must use the generic `action` parameter. This is to enforce the use of generic parameters where possible for maximum cross-platform modeling.
525
526 If you set both `accept` and `jump` parameters, you will get an error, because only one of the options should be set. Requires the `iptables` feature.
527
528 * `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 the `rate_limiting` feature.
529
530 * `line`: Read-only property for caching the rule line.
531
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
532 * `log_level`: When combined with `jump => 'LOG'` specifies the system log level to log to. Requires the `log_level` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
533
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
534 * `log_prefix`: When combined with `jump => 'LOG'` specifies the log prefix to use when logging. Requires the `log_prefix` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
535
536 * `mask`: Sets the mask to use when `recent` is enabled. Requires the `mask` feature.
537
538 * `name`: The canonical name of the rule. This name is also used for ordering, so make sure you prefix the rule with a number. For example:
539
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
540 ```puppet
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
541 firewall { '000 this runs first':
542 # this rule will run first
543 }
544 firewall { '999 this runs last':
545 # this rule will run last
546 }
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
547 ```
548
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
549 Depending on the provider, the name of the rule can be stored using the comment feature of the underlying firewall subsystem. Values must match '/^\d+[[:alpha:][:digit:][:punct:][:space:]]+$/'.
550
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
551 * `outiface`: Output interface to filter on. Values must match '/^!?\s?[a-zA-Z0-9\-\._\+\:]+$/'. Requires the `interface_match` feature. Supports interface alias (eth0:0) and negation.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
552
e0d8b64 @mhaskel README updates
mhaskel authored
553 * `physdev_in`: Match if the packet is entering a bridge from the given interface. Values must match '/^[a-zA-Z0-9\-\._\+]+$/'.
554
555 * `physdev_out`: Match if the packet is leaving a bridge via the given interface. Values must match '/^[a-zA-Z0-9\-\._\+]+$/'.
556
bd042a3 @jonnytpuppet Added code for physdev_is_bridged
jonnytpuppet authored
557 * `physdev_is_bridged`: Match if the packet is transversing a bridge. Valid values are true or false.
558
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
559 * `pkttype`: Sets the packet type to match. Valid values are: 'unicast', 'broadcast', and'multicast'. Requires the `pkttype` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
560
561 * `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-end number'. For example, '1-1024' would cover ports 1 to 1024.
562
563 * `proto`: The specific protocol to match for this rule. This is 'tcp' by default. Valid values are:
564 * 'tcp'
565 * 'udp'
566 * 'icmp'
a640a43 @jpds README.markdown: Added ipv{4,6} to proto list.
jpds authored
567 * 'ipv4'
568 * 'ipv6'
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
569 * 'ipv6-icmp'
570 * 'esp'
571 * 'ah'
572 * 'vrrp'
573 * 'igmp'
574 * 'ipencap'
575 * 'ospf'
576 * 'gre'
577 * 'all'
578
579 * `provider`: The specific backend to use for this firewall resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. Available providers are ip6tables and iptables. See the [Providers](#providers) section above for details about these providers.
580
4def60a Updates to format to fit style guide.
Lauren authored
581 * `random`: When using a `jump` value of 'MASQUERADE', 'DNAT', 'REDIRECT', or 'SNAT', this boolean will enable randomized port mapping. Valid values are true or false. Requires the `dnat` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
582
4def60a Updates to format to fit style guide.
Lauren authored
583 * `rdest`: If boolean 'true', adds the destination IP address to the list. Valid values are true or false. Requires the `recent_limiting` feature and the `recent` parameter.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
584
4def60a Updates to format to fit style guide.
Lauren authored
585 * `reap`: Can only be used in conjunction with the `rseconds` parameter. If boolean 'true', this will purge entries older than 'seconds' as specified in `rseconds`. Valid values are true or false. Requires the `recent_limiting` feature and the `recent` parameter.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
586
587 * `recent`: Enable the recent module. Valid values are: 'set', 'update', 'rcheck', or 'remove'. For example:
588
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
589 ```puppet
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
590 # If anyone's appeared on the 'badguy' blacklist within
591 # the last 60 seconds, drop their traffic, and update the timestamp.
592 firewall { '100 Drop badguy traffic':
593 recent => 'update',
594 rseconds => 60,
595 rsource => true,
596 rname => 'badguy',
597 action => 'DROP',
598 chain => 'FORWARD',
599 }
600 # No-one should be sending us traffic on eth0 from localhost
601 # Blacklist them
602 firewall { '101 blacklist strange traffic':
603 recent => 'set',
604 rsource => true,
605 rname => 'badguy',
606 destination => '127.0.0.0/8',
607 iniface => 'eth0',
608 action => 'DROP',
609 chain => 'FORWARD',
610 }
611 ```
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
612
613 Requires the `recent_limiting` feature.
614
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
615 * `reject`: When combined with `jump => 'REJECT'`, you can specify a different ICMP response to be sent back to the packet sender. Requires the `reject_type` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
616
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
617 * `rhitcount`: Used in conjunction with `recent => 'update'` or `recent => 'rcheck'`. When used, this will narrow the match to happen only when the address is in the list and packets greater than or equal to the given value have been received. Requires the `recent_limiting` feature and the `recent` parameter.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
618
619 * `rname`: Specify the name of the list. Takes a string argument. Requires the `recent_limiting` feature and the `recent` parameter.
620
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
621 * `rseconds`: Used in conjunction with `recent => 'rcheck'` or `recent => 'update'`. When used, this will narrow the match to only happen when the address is in the list and was seen within the last given number of seconds. Requires the `recent_limiting` feature and the `recent` parameter.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
622
623 * `rsource`: If boolean 'true', adds the source IP address to the list. Valid values are 'true', 'false'. Requires the `recent_limiting` feature and the `recent` parameter.
624
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
625 * `rttl`: May only be used in conjunction with `recent => 'rcheck'` or `recent => 'update'`. If boolean 'true', this will narrow the match to happen only when the address is in the list and the TTL of the current packet matches that of the packet that hit the `recent => 'set'` rule. If you have problems with DoS attacks via bogus packets from fake source addresses, this parameter may help. Valid values are 'true', 'false'. Requires the `recent_limiting` feature and the `recent` parameter.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
626
627 * `set_mark`: Set the Netfilter mark value associated with the packet. Accepts either 'mark/mask' or 'mark'. These will be converted to hex if they are not already. Requires the `mark` feature.
628
629 * `socket`: If 'true', matches if an open socket can be found by doing a socket lookup on the packet. Valid values are 'true', 'false'. Requires the `socket` feature.
630
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
631 * `source`: The source address. For example: `source => '192.168.2.0/24'`. You can also negate a mask by putting ! in front. For example: `source => '! 192.168.2.0/24'`. The source can also be an IPv6 address if your provider supports it.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
632
633 * `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-end number'. For example, '1-1024' would cover ports 1 to 1024.
634
5efdee6 @mhaskel MODULES-1612 - sync src_range and dst_range
mhaskel authored
635 * `src_range`: The source IP range. For example: `src_range => '192.168.1.1-192.168.1.10'`. The source IP range must be in 'IP1-IP2' format. Values in the range must be valid IPv4 or IPv6 addresses. Requires the `iprange` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
636
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
637 * `src_type`: Specify the source address type. For example: `src_type => 'LOCAL'`.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
638
639 Valid values are:
640
641 * 'UNSPEC': an unspecified address.
642 * 'UNICAST': a unicast address.
643 * 'LOCAL': a local address.
644 * 'BROADCAST': a broadcast address.
645 * 'ANYCAST': an anycast packet.
646 * 'MULTICAST': a multicast address.
647 * 'BLACKHOLE': a blackhole address.
648 * 'UNREACHABLE': an unreachable address.
649 * 'PROHIBIT': a prohibited address.
650 * 'THROW': an unroutable address.
651 * 'XRESOLVE': an unresolvable address.
652
653 Requires the `address_type` feature.
654
b8bd30b @hunner Update docs, remove feature, and rename property
hunner authored
655 * `stat_every`: Match one packet every nth packet. Requires `stat_mode => 'nth'`
656
657 * `stat_mode`: Set the matching mode for statistic matching. Supported modes are `random` and `nth`.
658
659 * `stat_packet`: Set the initial counter value for the nth mode. Must be between 0 and the value of `stat_every`. Defaults to 0. Requires `stat_mode => 'nth'`
660
661 * `stat_probability`: Set the probability from 0 to 1 for a packet to be randomly matched. It works only with `stat_mode => 'random'`.
662
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
663 * `state`: Matches a packet based on its state in the firewall stateful inspection table. Valid values are: 'INVALID', 'ESTABLISHED', 'NEW', 'RELATED'. Requires the `state_match` feature.
664
665 * `table`: Table to use. Valid values are: 'nat', 'mangle', 'filter', 'raw', 'rawpost'. By default the setting is 'filter'. Requires the `iptables` feature.
666
667 * `tcp_flags`: Match when the TCP flags are as specified. Set as 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'.
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
668
fe27d17 @jbondpdx Docs: Reference information added to firewall module readme
jbondpdx authored
669 Note that you specify flags in the order that iptables `--list` rules would list them to avoid having Puppet think you changed the flags. For 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. Requires the `tcp_flags` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
670
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
671 * `todest`: When using `jump => 'DNAT'`, you can specify the new destination address using this parameter. Requires the `dnat` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
672
673 * `toports`: For DNAT this is the port that will replace the destination port. Requires the `dnat` feature.
674
38f31ab @jbondpdx Docs: code formatting edits on readme
jbondpdx authored
675 * `tosource`: When using `jump => 'SNAT'`, you can specify the new source address using this parameter. Requires the `snat` feature.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
676
f45fa3b @nemski Add netmap feature and acceptance tests
nemski authored
677 * `to`: When using `jump => 'NETMAP'`, you can specify a source or destination subnet to nat to. Requires the `netmap` feature`.
678
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
679 * `uid`: UID or Username owner matching rule. Accepts a string argument only, as iptables does not accept multiple uid in a single statement. Requires the `owner` feature.
680
681 ###Type: firewallchain
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
682
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
683 Enables you to manage rule chains for firewalls.
684
685 Currently this type supports only iptables, ip6tables, and ebtables on Linux. It also provides support for setting the default policy on chains and tables that allow it.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
686
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
687 **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.
688
689 ####Providers
690
691 `iptables_chain` is the only provider that supports firewallchain.
692
693 ####Features
694
695 * `iptables_chain`: The provider provides iptables chain features.
696 * `policy`: Default policy (inbuilt chains only).
697
698 ####Parameters
699
700 * `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
701
4def60a Updates to format to fit style guide.
Lauren authored
702 * `ignore`: Regex to perform on firewall rules to exempt unmanaged rules from purging (when enabled). This is matched against the output of iptables-save. This can be a single regex or an array of them. To support flags, use the ruby inline flag mechanism: a regex such as '/foo/i' can be written as '(?i)foo' or '(?i:foo)'. Only when purge is 'true'.
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
703
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
704 Full example:
705 ```puppet
706 firewallchain { 'INPUT:filter:IPv4':
707 purge => true,
708 ignore => [
709 # ignore the fail2ban jump rule
710 '-j fail2ban-ssh',
711 # ignore any rules with "ignore" (case insensitive) in the comment in the rule
712 '--comment "[^"](?i:ignore)[^"]"',
713 ],
714 }
715 ```
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
716
717 * `name`: Specify the canonical name of the chain. For iptables the format must be {chain}:{table}:{protocol}.
718
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
719 * `policy`: Set the action the packet will perform when the end of the chain is reached. It can only be set on inbuilt chains ('INPUT', 'FORWARD', 'OUTPUT', 'PREROUTING', 'POSTROUTING'). Valid values are:
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
720
721 * 'accept': The packet is accepted.
722 * 'drop': The packet is dropped.
723 * 'queue': The packet is passed userspace.
724 * 'return': The packet is returned to calling (jump) queue or to the default of inbuilt chains.
725
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
726 * `provider`: The specific backend to use for this firewallchain resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. The only available provider is:
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
727
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
728 `iptables_chain`: iptables chain provider
5a5cfcd @alexjurkiewicz README cosmetics
alexjurkiewicz authored
729
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
730 * Required binaries: `ebtables-save`, `ebtables`, `ip6tables-save`, `ip6tables`, `iptables-save`, `iptables`.
731 * Default for `kernel` == `linux`.
732 * Supported features: `iptables_chain`, `policy`.
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
733
a957bca @jbondpdx Docs: Reference info added to firewall
jbondpdx authored
734 * `purge`: Purge unmanaged firewall rules in this chain. Valid values are 'false', 'true'.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
735
5e8eaed @mhaskel purge clarifications
mhaskel authored
736 **Note** This `purge` is purging unmanaged rules in a firewall chain, not unmanaged firewall chains. To purge unmanaged firewall chains, use the following instead.
737
738 ```puppet
739 resources { 'firewallchain':
740 purge => true
741 }
742 ```
743
b08e312 @kbarber Document ensure class parameter
kbarber authored
744 ###Fact: ip6tables_version
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
745
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
746 A Facter fact that can be used to determine what the default version of ip6tables is for your operating system/distribution.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
747
b08e312 @kbarber Document ensure class parameter
kbarber authored
748 ###Fact: iptables_version
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
749
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
750 A Facter fact that can be used to determine what the default version of iptables is for your operating system/distribution.
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
751
b08e312 @kbarber Document ensure class parameter
kbarber authored
752 ###Fact: iptables_persistent_version
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
753
754 Retrieves the version of iptables-persistent from your OS. This is a Debian/Ubuntu specific fact.
755
756 ##Limitations
757
730d496 Update the limitations documentation for SLES and Oracle Linux 5.
Ashley Penney authored
758 ###SLES
e52c08b @kbarber (maint) be clearer about what distributions we support
kbarber authored
759
4e7e233 Update the tests to not test socket on SLES.
Ashley Penney authored
760 The `socket` parameter is not supported on SLES. In this release it will cause
761 the catalog to fail with iptables failures, rather than correctly warn you that
762 the features are unusable.
e52c08b @kbarber (maint) be clearer about what distributions we support
kbarber authored
763
b22118f @hunner Change OEL limitation description
hunner authored
764 ###Oracle Enterprise Linux
7d37d6a @kbarber Clarify OS support
kbarber authored
765
b22118f @hunner Change OEL limitation description
hunner authored
766 The `socket` and `owner` parameters are unsupported on Oracle Enterprise Linux
767 when the "Unbreakable" kernel is used. These may function correctly when using
768 the stock RedHat kernel instead. Declaring either of these parameters on an
769 unsupported system will result in iptable rules failing to apply.
7d37d6a @kbarber Clarify OS support
kbarber authored
770
730d496 Update the limitations documentation for SLES and Oracle Linux 5.
Ashley Penney authored
771 ###Other
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
772
d2ace42 @skurylo (doc) Update link to JIRA
skurylo authored
773 Bugs can be reported using JIRA issues
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
774
d2ace42 @skurylo (doc) Update link to JIRA
skurylo authored
775 <http://tickets.puppetlabs.com>
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
776
777 ##Development
778
779 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.
780
781 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.
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
782
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
783 You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
784
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
785 For this particular module, please also read CONTRIBUTING.md before contributing.
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
786
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
787 Currently we support:
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
788
523ed21 @kbarber (#10163) Cleanup some of the inline documentation and README file to ali...
kbarber authored
789 * iptables
790 * ip6tables
9715882 @kbarber (#10162) Various fixes for firewallchain resource
kbarber authored
791 * ebtables (chains only)
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored
792
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
793 ###Testing
00b7ebc @kbarber Added some notes about how to run tests.
kbarber authored
794
795 Make sure you have:
796
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
797 * rake
798 * bundler
00b7ebc @kbarber Added some notes about how to run tests.
kbarber authored
799
800 Install the necessary gems:
801
bea3701 Update README to be consistent with module documentation template
Lauren Rother authored
802 bundle install
00b7ebc @kbarber Added some notes about how to run tests.
kbarber authored
803
804 And run the tests from the root of the source code:
805
806 rake test
5da92c8 @kbarber Initial start on rspec-system tests
kbarber authored
807
808 If you have a copy of Vagrant 1.1.0 you can also run the system tests:
809
a6d0f97 @MFredette Updates to Firewall Readme for review.
MFredette authored
810 RS_SET=ubuntu-1404-x64 rspec spec/acceptance
811 RS_SET=centos-64-x64 rspec spec/acceptance
Something went wrong with that request. Please try again.