Skip to content
Newer
Older
100644 210 lines (123 sloc) 4 KB
cf6e023 @saysjonathan fix readme header
saysjonathan authored May 9, 2011
1 ## puppetlabs-firewall module
bff53bd @saysjonathan initial commit
saysjonathan authored May 9, 2011
2
3 ### Overview
4
5 This is the puppet-firewall module. Here we are providing a module which can be used to configure various firewalls
6
7 ### Disclaimer
8
9 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.
10
11 Please see the included Apache Software License for more legal details regarding warranty.
12
13 ### Installation
14
15 From github, download the module into your modulepath on your Puppetmaster. If you are not sure where your module path is try this command:
16
55a2299 @kbarber Added some more examples and README cleanup.
kbarber authored Jun 15, 2011
17 puppet --configprint modulepath
bff53bd @saysjonathan initial commit
saysjonathan authored May 9, 2011
18
19 Depending on the version of Puppet, you may need to restart the puppetmasterd (or Apache) process before this module will work.
55a2299 @kbarber Added some more examples and README cleanup.
kbarber authored Jun 15, 2011
20
21 ### Quickstart
22
23 Once the module is in the correct modulepath, you should be able to create some
24 firewall rules like the below examples. Remember, that rules are lexically
25 ordered by the resource title at this point.
26
27 Basic accept ICMP request example:
28
29 firewall { "000 accept all icmp requests":
30 proto => "icmp",
31 jump => "ACCEPT",
32 }
33
34 Deny all:
35
36 firewall { "999 deny all other requests":
37 jump => "DENY",
38 }
1cfc642 @kbarber More doc improvements.
kbarber authored Jun 15, 2011
39
40 ### Supported firewalls
41
42 Currently we support:
43
44 * Iptables
45
46 But plans are to support lots of other firewall implementations:
47
48 * Linux IPv6 (ip6tables)
49 * FreeBSD (ipf)
50 * Mac OS X (ipfw)
51 * OpenBSD (pf)
52 * Cisco (ASA and basic access lists)
53
54 If you have knowledge in these rules and wish to contribute to this project
55 feel free to submit patches (after signing a Puppetlabs CLA :-).
00b7ebc @kbarber Added some notes about how to run tests.
kbarber authored Jun 15, 2011
56
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored Jun 20, 2011
57 ### Parameters
58
59 #### ensure
60
61 Creates rule when present, removes it when absent.
62
63 #### name
64
65 * namevar
66
67 Name of firewall rule. This at the moment also is used for ordering, so its
68 common practice to prefix all rules with numbers to force ordering. For example:
69
3cd7785 @kbarber Fix 1 line in doc.
kbarber authored Jun 20, 2011
70 name => "000 accept local traffic"
71
72 This will occur very early.
4c24e57 @kbarber Some initial parameter documentation for README.markdown.
kbarber authored Jun 20, 2011
73
74 #### chain
75
76 Name of the chain to use. Can be one of the built-ins:
77
78 * INPUT
79 * FORWARD
80 * OUTPUT
81 * PREROUTING
82 * POSTROUTING
83
84 The default value is 'INPUT'.
85
86 #### table
87
88 Table to use. Can be one of:
89
90 * nat
91 * mangle
92 * filter
93 * raw
94
95 By default the setting is 'filter'.
96
97 #### proto
98
99 Protocol to filter. By default this is 'tcp'.
100
101 #### jump
102
103 Action to perform when filter is matched. Can be one of:
104
105 * ACCEPT
106 * DROP
107 * QUEUE
108 * RETURN
109 * REJECT
110 * DNAT
111 * SNAT
112 * LOG
113 * MASQUERADE
114 * REDIRECT
115
116 The default value is 'ACCEPT'.
117
118 #### source
119
120 An array of source addresses. For example:
121
122 source => ['192.168.2.0/24', '10.2.3.0/24']
123
124 #### destination
125
126 An array of destination addresses to match. For example:
127
128 destination => ['192.168.2.0/24', '10.2.3.0/24']
129
130 #### sport
131
132 For protocols that support ports, this is a list of source ports to filter on.
133
134 #### dport
135
136 For protocols that support ports, this is a list of destination ports to filter on.
137
138 #### iniface
139
140 Input interface to filter on.
141
142 #### outiface
143
144 Output interface to filter on.
145
146 #### tosource
147
148 When using jump => "SNAT" you can specify the new source address using this
149 parameter.
150
151 #### todestination
152
153 When using jump => "DNAT" you can specify the new destination address using
154 this paramter.
155
156 #### toports
157
158 Specifies a range of ports to use for masquerade.
159
160 #### reject
161
162 When combined with jump => "REJECT" you can specify a different icmp response
163 to be sent back to the packet sender.
164
165 #### log_level
166
167 When combined with jump => "LOG" specifies the log level to log to.
168
169 #### log_prefix
170
171 When combined with jump => "LOG" specifies the log prefix to use when logging.
172
173 #### icmp
174
175 Specifies the type of ICMP to match.
176
177 #### state
178
179 When matching using stateful inspection you can match on different states such
180 as:
181
182 * INVALID
183 * ESTABLISHED
184 * NEW
185 * RELATED
186
187 #### limit
188
189 A rate to limit matched packets in the form of:
190
191 rate/[/second/|/minute|/hour|/day]
192
193 #### burst
194
195 Maximum initial packets to match before limit checks (above) apply.
196
00b7ebc @kbarber Added some notes about how to run tests.
kbarber authored Jun 15, 2011
197 ### Testing
198
199 Make sure you have:
200
201 rake
202
203 Install the necessary gems:
204
205 gem install rspec
206
207 And run the tests from the root of the source code:
208
209 rake test
Something went wrong with that request. Please try again.