Adoptable Cookbooks List

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

firewall Cookbook

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.

Requirements

Chef 12.4.x+ is required. We are currently testing against 12.8.1. If you need Chef 11 support, please try pinning back to a version less than 2.0, e.g.:
depends 'firewall', '< 2.0'

By default, Ubuntu chooses ufw. To switch to iptables, set this in an attribute file:
default['firewall']['ubuntu_iptables'] = true

By default, Red Hat & CentOS >= 7.0 chooses firewalld. To switch to iptables, set this in an attribute file:
default['firewall']['redhat7_iptables'] = true

Considerations that apply to all firewall providers and resources

This cookbook comes with two resources, firewall and firewall rule. The typical usage scenario is as follows:

run the :install action on the firewall resource named 'default', which installs appropriate packages and configures services to start on boot and starts them

run the :create action on every firewall_rule resource, which adds to the list of rules that should be configured on the firewall. firewall_rule then automatically sends a delayed notification to the firewall['default'] resource to run the :restart action.

run the delayed notification with action :restart on the firewall resource. 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 (DROP, ACCEPT, etc) is denoted as a command parameter on the firewall_rule resource.

Note -- in order to support multiple hash keys containing the same rule, anything found after the underscore will be stripped for: :OUTPUT :INPUT :POSTROUTING :PREROUTING COMMIT. This allows an example like the above to be reduced to just repeated lines of COMMIT and :OUTPUT ACCEPT while still avoiding duplication of other things.

default['firewall']['allow_established'] = true, set to false if you don't want a related/established default rule on iptables

default['firewall']['ipv6_enabled'] = true, set to false if you don't want IPv6 related/established default rule on iptables (this enables ICMPv6, which is required for much of IPv6 communication)

default['firewall']['firewalld']['permanent'] = false, set to true if you want firewalld rules to be added with --permanent so they survive a reboot. This will be changed to true by default in a future major version release.

Resources

firewall

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 firewall_name parameter.

Actions

: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 permanent firewalld rules (they are not persistent by default).

Parameters

disabled (default to 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.

ipv6_enabled (default to true): If set to false, firewall will not perform any ipv6 related work. Currently only supported in iptables.

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 :public.

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 :drop.

package_options: Used to pass options to the package install of firewall

firewall_rule

Actions

: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.

Parameters

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 ufw on the command line, or run using firewall-cmd.

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.

protocol: :tcp (default), :udp, :icmp, :none or protocol number. Using protocol numbers is not supported using the ufw provider (default for debian/ubuntu systems).

NOTE: 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. eth0).

dest_interface: interface where packets may be destined to go

redirect_port: redirected port for rules with command :redirect

logging: may be added to enable logging for a particular rule. valid values are: :connections, :packets. In the ufw provider, :connections logs new connections while :packets logs all packets.

Providers

See libraries/z_provider_mapping.rb for 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.

Troubleshooting

To figure out what the position values are for current rules, print the hash that contains the weights:
require pp
default_firewall = resources(:firewall, 'default')
pp default_firewall.rules

Development

This section details "quick development" steps. For a detailed explanation, see [[Contributing.md]].

Clone this repository from GitHub:

$ git clone git@github.com:chef-cookbooks/firewall.git

Create a git branch

$ git checkout -b my_bug_fix

Install dependencies:

$ bundle install

Make your changes/patches/fixes, committing appropiately

Write tests

Run the tests:

bundle exec foodcritic -f any .

bundle exec rspec

bundle exec rubocop

bundle exec kitchen test

In detail:
- 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

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.

v2.4.0 (2016-01-28)

Expose default iptables ruleset so that raw rules can be used in conjunction
with rulesets for other tables (#101).

v2.3.1 (2016-01-08)

Add raw rule support to the ufw firewall provider (#113).

v2.3.0 (2015-12-23)

Refactor logic so that firewall rules don't add a string rule to the firewall
when their actions run. Just run the action once on the firewall itself. This is
designed to prevent partial application of rules (#106)

Switch to "enabled" (positive logic) instead of "disabled" (negative logic) on
the firewall resource. It was difficult to reason with "disabled false" for some
complicated recipes using firewall downstream. disabled is now deprecated.

Add proper Windows testing and serverspec tests back into this cookbook.

Fix the port_to_s function so it also works for Windows (#111)

Fix typo checking action instead of command in iptables helper (#112)

Remove testing ranges of ports on CentOS 5.x, as it's broken there.

v2.2.0 (2015-11-02)

Added permanent as default option for RHEL 7 based systems using firewall-cmd.
This defaults to turned off, but it will be enabled by default on the next major version bump.

v2.1.0 (2015-10-15)

Minor feature release.
* Ensure ICMPv6 is open when ['firewall']['allow_established'] is set to true (the default). ICMPv6 is critical for most IPv6 operations.