cookbook 'firewall', '= 2.1.0'
Provides a set of primitives for managing firewalls and associated rules.
cookbook 'firewall', '= 2.1.0', :supermarket
knife supermarket install firewall
knife supermarket download firewall
Provides a set of primitives for managing firewalls and associated rules.
PLEASE NOTE - The resource/providers in this cookbook are under heavy development. An attempt is being made to keep the resource simple/stupid by starting with less sophisticated firewall implementations first and refactor/vet the resource definition with each successive provider.
Chef 12.4.x is required. We are currently testing against 12.4.1. If you need Chef 11 support, please try pinning back to a version less than 2.0, e.g.:
depends 'firewall', '< 2.0'
Supported firewalls and platforms
- UFW - Ubuntu, Debian
- IPTables - Red Hat & CentOS, Ubuntu
- FirewallD - Red Hat & CentOS >= 7.0 (IPv4 only support, needs contributions/testing)
- Windows Advanced Firewall - 2012 R2
* Ubuntu 12.04 & 14.04 with iptables, ufw
* Debian 7.8, 8.1 with ufw
* CentOS 5.11, 6.7 with iptables
* CentOS 7.1 with firewalld
* Windows Server 2012r2 with Windows Advanced Firewall
By default, Ubuntu chooses ufw. To switch to iptables, set this in an attribute file:
default['firewall']['ubuntu_iptables'] = true
Read this first
This cookbook comes with two resources, firewall and firewall rule. The typical usage scenario is as follows:
:installaction on the
firewallresource named 'default', which installs appropriate packages and configures services to start on boot and starts them
:createaction on every
firewall_ruleresource, which adds to the list of rules that should be configured on the firewall.
firewall_rulethen automatically sends a delayed notification to the
firewall['default']resource to run the
run the delayed notification with action
firewallresource. if any rules are different than the last run, the provider will update the current state of the firewall rules to match the expected rules.
There is a fundamental mismatch between the idea of a chef action and the action that should be taken on a firewall rule. For this reason, the chef action for a firewall_rule may be
:nothing (the rule should not be present in the firewall) or
:create (the rule should be present in the firewall), but the action taken on a packet in a firewall (
ACCEPT, etc) is denoted as a
command parameter on the
The default recipe creates a firewall resource with action install, and if
node['firewall']['allow_ssh'], opens port 22 from the world.
default['firewall']['ufw']['defaults']hash for template
default['firewall']['iptables']['defaults']hash for default policies for 'filter' table's chains`
default['firewall']['allow_ssh'] = false, set true to open port 22 for SSH when the default recipe runs
default['firewall']['allow_winrm'] = false, set true to open port 5989 for WinRM when the default recipe runs
default['firewall']['allow_established'] = true, set to false if you don't want a related/established default rule on iptables
NB: The name 'default' of this resource is important as it is used for firewall_rule providers to locate the firewall resource. If you change it, you must also supply the same value to any firewall_rule resources using the
:install(default action): Install and Enable the firewall. This will ensure the appropriate packages are installed and that any services have been started.
:disable: Disable the firewall. Drop any rules and put the node in an unprotected state. Flush all current rules. Also erase any internal state used to detect when rules should be applied.
:flush: Flush all current rules. Also erase any internal state used to detect when rules should be applied.
:save: Ensure all rules are added permanently under firewalld using
--permanent. Not supported on ufw, iptables. You must notify this action at the end of the chef run if you want persistent firewalld rules (they are not persistent by default).
false): If set to true, all actions will no-op on this resource. This is a way to prevent included cookbooks from configuring a firewall.
true): If set to false, firewall will not perform any ipv6 related work. Currently only supported in iptables.
log_level: UFW only. Level of verbosity the firewall should log at. valid values are: :low, :medium, :high, :full. default is :low.
rules: This is used internally for firewall_rule resources to append their rules. You should NOT touch this value unless you plan to supply an entire firewall ruleset at once, and skip using firewall_rule resources.
disabled_zone(firewalld only): The zone to set on firewalld when the firewall should be disabled. Can be any string in symbol form, e.g. :public, :drop, etc. Defaults to
enabled_zone(firewalld only): The zone to set on firewalld when the firewall should be enabled. Can be any string in symbol form, e.g. :public, :drop, etc. Defaults to
# all defaults firewall 'default' # enable platform default firewall firewall 'default' do action :install end # increase logging past default of 'low' firewall 'default' do log_level :high action :install end
:create(default action): If a firewall_rule runs this action, the rule will be recorded in a chef resource's internal state, and applied when providers automatically notify the firewall resource with action
:reload. The notification happens automatically.
firewall_name: the matching firewall resource that this rule applies to. Default value:
raw: Used to pass an entire rule as a string, omitting all other parameters. This line will be directly loaded by
iptables-restore, fed directly into
ufwon the command line, or run using
description(default: same as rule name): Used to provide a comment that will be included when adding the firewall rule.
position(default: 50): relative position to insert rule at. Position may be any integer between 0 < n < 100 (exclusive), and more than one rule may specify the same position.
command: What action to take on a particular packet
:allow(default action): the rule should allow matching packets
:deny: the rule should deny matching packets
:reject: the rule should reject matching packets
:masqerade: Masquerade the matching packets
:redirect: Redirect the matching packets
:log: Configure logging
stateful: a symbol or array of symbols, such as `
[:related, :established]that will be passed to the state module in iptables or firewalld.
:noneor protocol number. Using protocol numbers is not supported using the ufw provider (default for debian/ubuntu systems).
direction: For ufw, direction of the rule. valid values are:
Anywhere): source ip address or subnet to filter.
source_port(Default is nil): source port for filtering packets.
destination: ip address or subnet to filter on packet destination, must be a valid IP
dest_port: target port number (ie. 22 to allow inbound SSH), or an array of incoming port numbers (ie. [80,443] to allow inbound HTTP & HTTPS).
protocol attribute is required with multiple ports, or a range of incoming port numbers (ie. 60000..61000 to allow inbound mobile-shell. NOTE:
protocol, or an attribute is required with a range of ports.
interface: (source) interface to apply rule (ie.
dest_interface: interface where packets may be destined to go
redirect_port: redirected port for rules with command
logging: may be added to enable logging for a particular rule. valid values are:
:packets. In the ufw provider,
:connectionslogs new connections while
:packetslogs all packets.
# open standard ssh port firewall_rule 'ssh' do port 22 command :allow end # open standard http port to tcp traffic only; insert as first rule firewall_rule 'http' do port 80 protocol :tcp position 1 command :allow end # restrict port 13579 to 10.0.111.0/24 on eth0 firewall_rule 'myapplication' do port 13579 source '10.0.111.0/24' direction :in interface 'eth0' command :allow end # specify a protocol number (supported on centos/redhat) firewall_rule 'vrrp' do protocol 112 command :allow end # use the iptables provider to specify protocol number on debian/ubuntu firewall_rule 'vrrp' do provider Chef::Provider::FirewallRuleIptables protocol 112 command :allow end # open UDP ports 60000..61000 for mobile shell (mosh.mit.edu), note # that the protocol attribute is required when using port_range firewall_rule 'mosh' do protocol :udp port 60000..61000 command :allow end # open multiple ports for http/https, note that the protocol # attribute is required when using ports firewall_rule 'http/https' do protocol :tcp port [80, 443] action :allow end firewall 'default' do disabled true action :nothing end
libraries/z_provider_mapping.rbfor a full list of providers for each platform and version.
Different providers will determine the current state of the rules differently -- parsing the output of a command, maintaining the state in a file, or some other way. If the firewall is adjusted from outside of chef (non-idempotent), it's possible that chef may be caught unaware of the current state of the firewall. The best workaround is to add a
:flush action to the firewall resource as early as possible in the chef run, if you plan to modify the firewall state outside of chef.
To figure out what the position values are for current rules, print the hash that contains the weights:
default_firewall = resources(:firewall, 'default')
This section details "quick development" steps. For a detailed explanation, see [[Contributing.md]].
Clone this repository from GitHub:
$ git clone email@example.com:chef-cookbooks/firewall.git
Create a git branch
$ git checkout -b my_bug_fix
$ bundle install
Make your changes/patches/fixes, committing appropiately
Run the tests:
bundle exec foodcritic -f any .
bundle exec rspec
bundle exec rubocop
bundle exec kitchen test
- Foodcritic will catch any Chef-specific style errors
- RSpec will run the unit tests
- Rubocop will check for Ruby-specific style errors
- Test Kitchen will run and converge the recipes
License & Authors
- Author:: Seth Chisamore (firstname.lastname@example.org)
- Author:: Ronald Doorn (email@example.com)
- Author:: Martin Smith (firstname.lastname@example.org)
- Author:: Sander van Harmelen (email@example.com)
Copyright:: 2011-2015, Chef Software, Inc Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
|chef-sugar >= 0.0.0|
firewall Cookbook CHANGELOG
This file is used to list changes made in each version of the firewall cookbook.
Minor feature release.
* Ensure ICMPv6 is open when
['firewall']['allow_established'] is set to true (the default). ICMPv6 is critical for most IPv6 operations.
Minor bugfix release.
* Ensure provider filtering always yields 1 and only 1 provider, #97 & #98
* Documentation update #96
Minor bugfix release.
* Allow override of filter chain policies, #94
* Fix foodcrtitic and chefspec errors
Minor bugfix release.
* Fix wrong conditional for firewalld ports, #93
* Fix ipv6 command logic under iptables, #91
- Release with working CI, Chefspec matchers.
- Add default related/established rule for iptables
- #84, major rewrite:
- Allow relative positioning of rules
- Use delayed notifications to create one firewall ruleset instead of incremental changes
- Remove poise dependency
- #82 - Introduce Windows firewall support and test-kitchen platform.
- #73 - Add the option to disable ipv6 commands on iptables
- #78 - Use Chef-12 style
providesto address provider mapping issues
- Rubocop and foodcritic cleanup
- #80 - Remove an extra space in port range
- #68 - Install firewalld when it does not exist
- #72 - Fix symbol that was a string, breaking comparisons
- #75 - Use correct service in iptables save action, Add serverspec tests for iptables suite
- #74 - add :save matcher for Chefspec
- #70 - Add chef service resource to ensure firewall-related services are enabled/disabled
- - Add testing and support for iptables on ubuntu in iptables provider
- #69 - Support for CentOS/RHEL 5.x
- #63 - Add support for protocol numbers
- #64 - Support the newer version of poise
- #60 - Always add /32 or /128 to ipv4 or ipv6 addresses, respectively.
- Make comment quoting optional; iptables on Ubuntu strips quotes on strings without any spaces
- #57 - Suppress warning: already initialized constant XXX while Chefspec
- #56 - Better ipv6 support for firewalld and iptables
- #54 - Document raw parameter
- #52 - Typo in :masquerade action name
- #49 - Fix position attribute of firewall_rule providers to be correctly used as a string in commands
- Major upgrade and rewrite as HWRP using poise
- Adds support for iptables and firewalld
- Modernize tests and other files
- Fix many bugs from ufw defaults to multiport suppot
- Corrects issue where on a secondary converge would not distinguish between inbound and outbound rules
[COOK-4385] - UFW provider is broken
[COOK-4140] Only notify when a rule is actually added
- COOK-3615 - Install required UFW package on Debian
- [COOK-2932]: ufw providers work on debian but cannot be used
- [COOK-2250] - improve readme
- [COOK-1234] - allow multiple ports per rule
- [COOK-1615] - Firewall example docs have incorrect direction syntax
The default action for firewall LWRP is now :enable, the default action for firewall_rule LWRP is now :reject. This is in line with a "default deny" policy.
- [COOK-1429] - resolve foodcritic warnings
- refactor all resources and providers into LWRPs
- removed :reset action from firewall resource (couldn't find a good way to make it idempotent)
- removed :logging action from firewall resource...just set desired level via the log_level attribute
- [COOK-725] Firewall cookbook firewall_rule LWRP needs to support logging attribute.
- Firewall cookbook firewall LWRP needs to support :logging
- [COOK-696] Firewall cookbook firewall_rule LWRP needs to support interface
- [COOK-697] Firewall cookbook firewall_rule LWRP needs to support the direction for the rules
- [COOK-695] Firewall cookbook firewall_rule LWRP needs to support destination port
- [COOK-709] fixed :nothing action for the 'firewall_rule' resource.
- [COOK-694] added :reject action to the 'firewall_rule' resource.
- [COOK-698] added :reset action to the 'firewall' resource.
- Add missing 'requires' statements. fixes 'NameError: uninitialized constant' error. thanks to Ernad Husremović for the fix.
- [COOK-686] create firewall and firewall_rule resources
- [COOK-687] create UFW providers for all resources
2.1.0 passed this metric
2.1.0 passed this metric