From 523ed212c3a7e0924be2c3d13247b14fb0c0a730 Mon Sep 17 00:00:00 2001 From: Ken Barber Date: Wed, 19 Oct 2011 08:57:48 +0100 Subject: [PATCH] (#10163) Cleanup some of the inline documentation and README file to align with general forge usage. * The README.markdown file had a lot of property information that was duplicated in the type itself. The README.markdown file has more info in some cases, I have moved this into the type. * The README.markdown lacked documentation on how to install the module using the forge which meant users accessing it via github would be inclined to download the development version from github instead. * Cleaned up doc string alignments and made it consistent with all types. --- Modulefile | 2 +- README.markdown | 254 ++++++++++-------------------------- lib/puppet/type/firewall.rb | 234 +++++++++++++++++++++++++-------- 3 files changed, 246 insertions(+), 244 deletions(-) diff --git a/Modulefile b/Modulefile index ca185f1..3004a81 100644 --- a/Modulefile +++ b/Modulefile @@ -5,4 +5,4 @@ author 'puppetlabs' license 'ASL 2.0' summary 'Firewall Module' description 'Manages Firewalls such as iptables' -project_page 'https://github.com/puppetlabs/puppetlabs-firewall' +project_page 'http://forge.puppetlabs.com/puppetlabs/firewall' diff --git a/README.markdown b/README.markdown index 5803df1..e439657 100644 --- a/README.markdown +++ b/README.markdown @@ -1,35 +1,67 @@ ## puppetlabs-firewall module +## User Guide + ### Overview -This is the puppet-firewall module. Here we are providing a module which can be used to configure various firewalls +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. +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 -Please see the included Apache Software License for more legal details regarding warranty. +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 -From github, download the module into your modulepath on your Puppetmaster. If you are not sure where your module path is try this command: +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 -Depending on the version of Puppet, you may need to restart the puppetmasterd (or Apache) process before this module will work. +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: +Depending on the version of Puppet, you may need to restart the +puppetmasterd (or Apache) process before this module will work. + +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. -### Quickstart - -Once the module is in the correct modulepath, you should be able to create some -firewall rules like the below examples. Remember, that rules are lexically -ordered by the resource title at this point. +### Examples Basic accept ICMP request example: @@ -38,7 +70,7 @@ Basic accept ICMP request example: action => "accept", } -Deny all: +Drop all: firewall { "999 drop all other requests": action => "drop", @@ -69,7 +101,7 @@ You can make firewall rules persistent with the following iptables example: } 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 +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 { @@ -86,196 +118,48 @@ last rules should run, this however should belong in a puppet module. 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. -### Supported firewalls - -Currently we support: - -* Iptables - -But plans are to support lots of other firewall implementations: - -* Linux IPv6 (ip6tables) -* FreeBSD (ipf) -* Mac OS X (ipfw) -* OpenBSD (pf) -* Cisco (ASA and basic access lists) - -If you have knowledge in these rules and wish to contribute to this project -feel free to submit patches (after signing a Puppetlabs CLA :-). - -### Generic Properties - -#### ensure - -Creates rule when present, removes it when absent. - -#### name - -* namevar - -Name of firewall rule. This at the moment also is used for ordering, so its -common practice to prefix all rules with numbers to force ordering. For example: - - name => "000 accept local traffic" - -This will occur very early. - -#### 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'). - -#### proto - -Protocol to filter. By default this is 'tcp'. - -#### source - -An array of source addresses. For example: - - source => ['192.168.2.0/24', '10.2.3.0/24'] - -#### destination - -An array of destination addresses to match. For example: +### Further documentation - destination => ['192.168.2.0/24', '10.2.3.0/24'] +More documentation is available from the forge for each release: -#### sport + -For protocols that support ports, this is a list of source ports to filter on. +Or you can access the inline documentation: -#### dport + puppet describe firewall -For protocols that support ports, this is a list of destination ports to filter on. +Or: -### Iptables Properties + puppet doc -r type -#### chain +(and search for firewall). -Name of the chain to use. Can be one of the built-ins: +### Bugs -* INPUT -* FORWARD -* OUTPUT -* PREROUTING -* POSTROUTING +Bugs can be reported in the Puppetlabs Redmine project: -Or you can provide a user-based chain. + -The default value is 'INPUT'. +## Developer Guide -#### table +### Contributing -Table to use. Can be one of: +Make sure you read CONTRIBUTING.md before contributing. -* nat -* mangle -* filter -* raw -* rawpost - -By default the setting is 'filter'. - -#### jump - -Action to perform when filter is matched for iptables. Can be one of: - -* 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. - -### Interface Matching Properties - -#### iniface - -Input interface to filter on. - -#### outiface - -Output interface to filter on. - -### NAT Properties - -#### tosource - -When using jump => "SNAT" you can specify the new source address using this -parameter. - -#### todestination - -When using jump => "DNAT" you can specify the new destination address using -this paramter. - -#### toports - -Specifies a range of ports to use for masquerade. - -### Reject Properties - -#### reject - -When combined with jump => "REJECT" you can specify a different icmp response -to be sent back to the packet sender. - -### Logging Properties - -#### log_level - -When combined with jump => "LOG" specifies the log level to log to. - -#### log_prefix - -When combined with jump => "LOG" specifies the log prefix to use when logging. - -### ICMP Matching Properties - -#### icmp - -Specifies the type of ICMP to match. - -### State Matching Properties - -#### state - -When matching using stateful inspection you can match on different states such -as: - -* INVALID -* ESTABLISHED -* NEW -* RELATED - -### Rate Limiting Properties - -#### limit +Currently we support: -A rate to limit matched packets in the form of: +* iptables +* ip6tables - rate/[/second/|/minute|/hour|/day] +But plans are to support lots of other firewall implementations: -#### burst +* FreeBSD (ipf) +* Mac OS X (ipfw) +* OpenBSD (pf) +* Cisco (ASA and basic access lists) -Maximum initial packets to match before limit checks (above) apply. +If you have knowledge in these technology, know how to code and wish to contribute +to this project we would welcome the help. ### Testing diff --git a/lib/puppet/type/firewall.rb b/lib/puppet/type/firewall.rb index 52844d9..2eb8751 100644 --- a/lib/puppet/type/firewall.rb +++ b/lib/puppet/type/firewall.rb @@ -4,8 +4,10 @@ require 'puppet/util/firewall' Puppet::Type.newtype(:firewall) do include Puppet::Util::Firewall - @doc = "This type provides the capability to manage firewall rules within - puppet." + @doc = <<-EOS + This type provides the capability to manage firewall rules within + puppet. + EOS feature :rate_limiting, "Rate limiting features." feature :snat, "Source NATing" @@ -21,7 +23,9 @@ Puppet::Type.newtype(:firewall) do feature :iptables, "The provider provides iptables features." ensurable do - desc "Manage the state of this rule." + desc <<-EOS + Manage the state of this rule. The default action is *present*. + EOS newvalue(:present) do provider.insert @@ -35,7 +39,16 @@ Puppet::Type.newtype(:firewall) do end newparam(:name) do - desc "The canonical name of the rule." + desc <<-EOS + 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. + EOS isnamevar # Keep rule names simple - they must start with a number @@ -43,22 +56,45 @@ Puppet::Type.newtype(:firewall) do end newproperty(:action) do - desc "Action to perform on this rule." + desc <<-EOS + 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*). + EOS newvalues(:accept, :reject, :drop) end # Generic matching properties newproperty(:source) do - desc "The source IP address to match." + desc <<-EOS + 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. + EOS end newproperty(:destination) do - desc "The destination IP address to match." + desc <<-EOS + 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. + EOS end newproperty(:sport, :array_matching => :all) do - desc "The source port to match for this filter (if the protocol supports - ports). Will accept a single element or an array." + desc <<-EOS + For protocols that support ports, this is a list of source ports + to filter on. + EOS munge do |value| @resource.string_to_port(value) @@ -71,8 +107,10 @@ Puppet::Type.newtype(:firewall) do end newproperty(:dport, :array_matching => :all) do - desc "The destination port to match for this filter (if the protocol - supports ports). Will accept a single element or an array." + desc <<-EOS + For protocols that support ports, this is a list of destination + ports to filter on. + EOS munge do |value| @resource.string_to_port(value) @@ -85,97 +123,156 @@ Puppet::Type.newtype(:firewall) do end newproperty(:proto) do - desc "The specific protocol to match for this rule." + desc <<-EOS + The specific protocol to match for this rule. By default this is + *tcp*. + EOS + newvalues(:tcp, :udp, :icmp, :"ipv6-icmp", :esp, :ah, :vrrp, :igmp, :all) defaultto "tcp" end # Iptables specific newproperty(:chain, :required_features => :iptables) do - desc "The value for the iptables -A parameter. Normal values are: 'INPUT', - 'FORWARD', 'OUTPUT', 'PREROUTING', 'POSTROUTING' but you can also - specify a user created chain." + desc <<-EOS + 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'. + EOS defaultto "INPUT" newvalue(/^[a-zA-Z0-9\-_]+$/) end newproperty(:table, :required_features => :iptables) do - desc "The value for the iptables -t parameter." + desc <<-EOS + Table to use. Can be one of: + + * nat + * mangle + * filter + * raw + * rawpost + + By default the setting is 'filter'. + EOS + newvalues(:nat, :mangle, :filter, :raw, :rawpost) defaultto "filter" end newproperty(:jump, :required_features => :iptables) do - desc < :interface_match) do - desc "Match input interface." + desc <<-EOS + Input interface to filter on. + EOS newvalues(/^[a-zA-Z0-9\-_]+$/) end newproperty(:outiface, :required_features => :interface_match) do - desc "Match ouput interface." + desc <<-EOS + Output interface to filter on. + EOS newvalues(/^[a-zA-Z0-9\-_]+$/) end # NAT specific properties newproperty(:tosource, :required_features => :snat) do - desc "For SNAT this is the IP address that will replace the source IP - address." + desc <<-EOS + When using jump => "SNAT" you can specify the new source address using + this parameter. + EOS end newproperty(:todest, :required_features => :dnat) do - desc "For DNAT this is the IP address that will replace the destination IP - address." + desc <<-EOS + When using jump => "DNAT" you can specify the new destination address + using this paramter. + EOS end newproperty(:toports, :required_features => :dnat) do - desc "For DNAT this is the port that will replace the destination port." + desc <<-EOS + For DNAT this is the port that will replace the destination port. + EOS end # Reject ICMP type newproperty(:reject, :required_features => :reject_type) do - desc "The ICMP response to reject a packet with." + desc <<-EOS + When combined with jump => "REJECT" you can specify a different icmp + response to be sent back to the packet sender. + EOS end # Logging properties newproperty(:log_level, :required_features => :log_level) do - desc "The syslog level to log to." + desc <<-EOS + When combined with jump => "LOG" specifies the system log level to log + to. + EOS end newproperty(:log_prefix, :required_features => :log_prefix) do - desc "The syslog prefix." + desc <<-EOS + When combined with jump => "LOG" specifies the log prefix to use when + logging. + EOS end # ICMP matching property newproperty(:icmp, :required_features => :icmp_match) do - desc "When matching ICMP packets, this is the type of ICMP packet to match." + desc <<-EOS + When matching ICMP packets, this is the type of ICMP packet to match. + EOS munge do |value| if value.kind_of?(String) @@ -191,9 +288,18 @@ EOS end end - newproperty(:state, :array_matching => :all, :required_features => :state_match) do - desc "Matches a packet based on its state in the firewall stateful inspection - table." + newproperty(:state, :array_matching => :all, :required_features => + :state_match) do + + desc <<-EOS + Matches a packet based on its state in the firewall stateful inspection + table. Values can be: + + * INVALID + * ESTABLISHED + * NEW + * RELATED + EOS newvalues(:INVALID,:ESTABLISHED,:NEW,:RELATED) @@ -205,17 +311,25 @@ EOS # Rate limiting properties newproperty(:limit, :required_features => :rate_limiting) do - desc "Rate limiting value. Example values are: '50/sec', '40/min', - '30/hour', '10/day'." + desc <<-EOS + 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'." + EOS end newproperty(:burst, :required_features => :rate_limiting) do - desc "Rate limiting burst value (per second)." + desc <<-EOS + Rate limiting burst value (per second) before limit checks apply. + EOS newvalue(/^\d+$/) end newparam(:line) do - desc 'Read-only property for caching the rule line' + desc <<-EOS + Read-only property for caching the rule line. + EOS end validate do @@ -230,7 +344,9 @@ EOS end # First we make sure the chains and tables are valid combinations - if value(:table).to_s == "filter" && value(:chain) =~ /PREROUTING|POSTROUTING/ + if value(:table).to_s == "filter" && + value(:chain) =~ /PREROUTING|POSTROUTING/ + self.fail "PREROUTING and POSTROUTING cannot be used in table 'filter'" end @@ -238,7 +354,9 @@ EOS self.fail "INPUT and FORWARD cannot be used in table 'nat'" end - if value(:table).to_s == "raw" && value(:chain) =~ /INPUT|FORWARD|POSTROUTING/ + if value(:table).to_s == "raw" && + value(:chain) =~ /INPUT|FORWARD|POSTROUTING/ + self.fail "INPUT, FORWARD and POSTROUTING cannot be used in table raw" end -- 2.45.2