Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

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.

Select Badges

Select Supported Platforms

Select Status

RSS

diptables (14) Versions 1.1.0

A smart iptables cookbook for Chef!

Policyfile
Berkshelf
Knife
cookbook 'diptables', '= 1.1.0', :supermarket
cookbook 'diptables', '= 1.1.0'
knife supermarket install diptables
knife supermarket download diptables
README
Dependencies
Changelog
Quality 100%

Diptables cookbook

A Chef cookbook with to manage iptables rules and policies.

WARNING: Chef 11 is no longer supported by this cookbook. Please use version
1.0.1 if you still use Chef 11, or better yet, upgrade your Chef client!

Usage

This cookbook rebuilds the entire set of rules at every Chef-client run, thus
making it trivial to keep the iptables configuration up-to-date.

It also makes it easy to create iptables rules using Chef search queries. For
example, you can very simply create a rule telling your database server to let
all your backend servers connect to it.

You simply need to create all the rules and policies using the resources
provided by this cookbook (see below), and then apply them using with a
diptables_apply resource or alternatively by including diptables::default.
Note that if you do not do either of these things, this cookbook defines a
handler that will apply the rules for you at the end of the run (but that's not
recommended, as you won't benefit from your reporting handlers if there's an
error applying rules that way).

Requirements

This cookbook is fully tested on Ubuntu 12.04, 14.04, CentOS 6.5, and Chef 12.

It should work on any platform that supports iptables though.

Resources

diptables_rule

The most generic resource to define rules. If you want to apply TCP or UDP
rules, you might want to have a look at diptables_tcp_udp_rule below that
brings so syntactic sugar on top of this diptables_rule.

Actions:

Action Description
:append (default) Appends the rule after the other rules already defined in its chain
:prepend Prepends the rule the front of its chain
:insert Inserts the rule in its chain at the position given by the index attribute (see below)
:add (deprecated) An alis for :append

Attributes:

Attribute Type Default Description
table String 'filter' The rule's table
chain String 'INPUT The rule's chain
rule `String Array` ''
jump `String FalseClass` ACCEPT
comment `String TrueClass FalseClass`
query `String FalseClass` false
placeholders Hash {} When using the query attribute, this defines how to replace placeholders from the rule; it should map each placeholder's name to a method name or an attribute path (given as arrrays) used to retrieve the corresponding values from the Chef::Node objects returned by the query
same_environment `TrueClass FalseClass` false
index Fixnum -1 The rule's index in its chain (only makes sense with the :insert action)

A few examples (note that all these would be simpler with diptables_tcp_udp_rule resources instead):

# Disallow SSH
diptables_rule 'ssh' do
  rule '--proto tcp --dport 22'
  jump 'REJECT'
end

# Allow HTTP, HTTPS
diptables_rule 'http' do
  rule [ '--proto tcp --dport 80',
         '--proto tcp --dport 443' ]
end

# Allow backend servers to connect to MySQL (using a node method)
diptables_rule 'mysql with node method' do
  rule '-s %s --proto tcp --dport 3306'
  query 'roles:backend-server'
  placeholders({:remote_ip => 'ipaddress'})
end

And the same as the above, but using node attributes instead (assuming
node['my_company']['network']['internal_ip'] is defined):

# Allow backend servers to connect to MySQL (using an attribute path)
diptables_rule 'mysql with attribute path' do
  rule '-s %s --proto tcp --dport 3306'
  query 'roles:backend-server'
  placeholders({:remote_ip => ['my_company', 'network', 'internal_ip]})
end

diptables_tcp_udp_rule

Essentially a wrapper with some syntactic sugar on top of diptables_rule.

Same actions as diptables_rule.

Attributes:

Attribute Type Default Description
table String 'filter' The rule's table
chain String 'INPUT The rule's chain
jump `String FalseClass` ACCEPT
proto `'tcp' 'udp'` 'tcp'
interface `String FalseClass` false
dport `Fixnum String Array
source `String Array FalseClass`
source_query `String FalseClass` false
source_method `String Array` 'ipaddress'
comment `String TrueClass FalseClass`
same_environment `TrueClass FalseClass` false
index Fixnum -1 The rule's index in its chain (only makes sense with the :insert action)

The same examples as above, re-written using diptables_tcp_udp_rules:

# Disallow SSH
diptables_tcp_udp_rule 'ssh' do
  dport 22
  jump 'REJECT'
end

# Allow HTTP, HTTPS
diptables_tcp_udp_rule 'http' do
  dport [80, 443]
end

# Allow backend servers to connect to MySQL (using a node method)
diptables_tcp_udp_rule 'mysql with node method' do
  dport 3306
  source_query 'roles:backend-server'
end

# Allow backend servers to connect to MySQL (using an attribute path)
diptables_tcp_udp_rule 'mysql with attribute path' do
  dport 3306
  query 'roles:backend-server'
  source_method ['my_company', 'network', 'internal_ip]
end

diptables_bpf_rule

Another wrapper on top of diptables_rule; that one allows to create BPF ("Berkeley Packet Filter") rules
using the same syntax as for tcpdump filters.

This one is very specific, and you probably won't use it, so just a couple of
examples here:

# drops all IPv6 traffic
diptables_bpf_rule 'drop all IPv6 traffic' do
    tcpdump_rule 'ip6'
    jump 'DROP'
end

A more sophisticated example, that accepts all IP packets where the source and
destination IP do not belong to the same /16 network on tun0:

diptables_bpf_rule 'accept only traffic on the same /16 network' do
    tcpdump_rule 'ip and ip[12:4] & 0xFFFF0000 = ip[16:4] & 0xFFFF0000'
    # WARNING: this interface is only used to generate the bytecode, not for the
    # actual iptables rule!
    interface 'tun0'
    additional_rule '-i tun0'
end

Of course assumes you have the bpf iptables module installed. You also need
to have tcpdump around.

More docs and example at https://github.com/cloudflare/bpftools

diptables_policy

Defines a policy (default action) for a given iptables chain.

Actions:

Action Description
:add (default) Adds the policy

Attributes:

Attribute Type Default Description
table String 'filter' The policy's table
chain String 'INPUT The policy's chain
policy `'ACCEPT' 'DROP'` none (required)

diptables_apply

Action Description
:apply (default) Applies the iptables configuration as defined so far

Applies rules and policies defined so far. There must be exactly one
diptables_apply resource in your Chef-client run, and it must be converged
after all your rule and policy resources (if you have more than one, Chef
will output an explicit warning).

Note that the diptables::default recipe defines such a resource. As mentioned
above, if your Chef-client run ends with one or more rule or policy resources
that haven't been applied yet, our custom Chef handler will create and converge
a diptables_apply resource on the fly, but it is not recommended to rely on
this behaviour.

Contributing & Feedback

As always, I appreciate bug reports, suggestions, pull requests, feedback...
Feel free to reach me at wk8.github@gmail.com

Development & Testing

You can test this cookbook locally, provided you have a bunch of free software
installed, namely Vagrant,
Berkshelf, VirtualBox,
and a couple of Vagrant plugins:
Vagrant-Berkshelf and
Vagrant-Omnibus.

Then playing with this cookbook should be as easy as running bundle install && vagrant up!

To run the full test suite across all supported platforms and Chef versions,
you need to have ChefDK around, and run
kitchen test.

Chef-Solo

As of version 0.1.5, you can use this cookbook's resources' query abilities as
long as you have the chef-solo-search cookbook (by
edelight)
installed.

Please note though that the chef-solo-search cookbook is deprecated, and you
should really consider starting using chef-zero instead as suggested by
chef-solo-search's author
himself.

Changes

  • 1.1.0 (May 2nd, 2016):

    • Upgraded the syntax to Chef 12. Deprecated support for Chef 11
    • Upgraded the dev environment
  • 1.0.1 (Sep 19, 2015)

    • Added the ['diptables']['force_reload'] attribute to explicitely reload rules even when the rules file has not been modified - not adding to the README as this is a smell in Chef use as far as I'm concerned
  • 1.0.0 (Apr 24, 2015)

    • Added full support for CentOS 6.5
    • Added rspec tests
    • Added Test-Kitchen tests for all supported platforms and Chef versions
    • Migrated the applying logic to the diptables_apply resource
  • 0.2.0 (Mar 1, 2015)

    • Added the diptables_bpf_rule resource
  • 0.1.6 (May 6, 2014)

    • Included Vagrant & Berkshelf for easier development
  • 0.1.5 (Apr 26, 2014)

    • Enabling the use of the search queries with Chef-Solo if the chef-solo-search cookbook is installed
    • Enforcing that the default recipe runs after LWRPs have been defined in a smoother way
  • 0.1.4 (Nov 6, 2013)

    • Sorting the query's results to avoid reloading iptables unnecessarily
  • 0.1.3 (Oct 8, 2013)

    • Forcing the flush of the test chain, fixing a possible bug when a previous Chef-client run has been killed half-way through
  • 0.1.2 (Sep 23, 2013)

    • Forcing the iptables reload action when disabling the dry_run mode
    • Fixing possible name collision
  • 0.1.1 (Sep 23, 2013)

    • Added the comment attribute
  • 0.1.0 (Sep 11, 2013)

    • Initial release

Dependent cookbooks

chef_handler >= 0.0.0

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

CHANGELOG for diptables

This file is used to list changes made in each version of diptables.

1.1.0:

  • Upgraded the syntax to Chef 12. Deprecated support for Chef 11
  • Upgraded the dev environment

1.0.1:

  • Added the ['diptables']['force_reload'] attribute to explicitely reload rules even when the rules file has not been modified - not adding to the README as this is a smell in Chef use as far as I'm concerned

1.0.0:

  • Added full support for CentOS 6.5
  • Added rspec tests
  • Added Test-Kitchen tests for all supported platforms and Chef versions
  • Migrated the applying logic to the diptables_apply resource

0.2.0:

  • Added the diptables_bpf_rule resource

0.1.6:

  • Included Vagrant & Berkshelf for easier development

0.1.5:

  • Enabling the use of the search queries with Chef-Solo if the chef-solo-search cookbook is installed
  • Enforcing that the default recipe runs after LWRPs have been defined in a smoother way

0.1.4:

  • Sorting the query's results to avoid reloading iptables unnecessarily

0.1.3:

  • Forcing the flush of the test chain, fixing a possible bug when a previous Chef-client run has been killed half-way through

0.1.2:

  • Forcing the iptables reload action when disabling the dry_run mode
  • Fixing possible name collision

0.1.1:

  • Added the comment attribute

0.1.0:

  • Initial release of diptables

Foodcritic Metric
            

1.1.0 passed this metric