tcpwrappers

master branch:

Table of Contents

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with tcpwrappers
   • What tcpwrappers affects
   • Beginning with tcpwrappers
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Module Description

The tcpwrappers module allows for the installation and configuration of access rules.

Upon inclusion of the class, it will install the tcpwrappers package and set the hosts.allow and hosts.deny files to what was originally included on the operating system with the addition of a warning comment at the top of the file that the hosts.allow and hosts.deny file are now managed via puppet.

Warning: If this class is applied to a system with hosts.allow and/or hosts.deny rules already present, those rules will be removed.

Setup

What tcpwrappers affects

• Package(s): RedHat osfamily: tcp_wrappers.
• File: RedHat osfamily: /etc/hosts.allow
• File: RedHat osfamily: /etc/hosts.deny

Beginning with tcpwrappers

include tcpwrappers should be all that is needed to install and configure tcpwrappers to the system defaults.

Usage

All parameters to the main class can be passed via puppet code or hiera.

Note: By default when using hiera data, the first encountered instance of the key tcpwrappers::allows::rules will be used. It is possible to generate a merged hash of tcpwrappers::allows::rules from across multiple hiera data files if lookup_options are specified. Please see the examples below for details.

Some examples are presented below showing the purpose of some of the parameters of classes of the module. Those generating rules in hosts.allow show how to create those rules similar to those listed in the RedHat/CentOS tcpwrappers documentation.

Install tcpwrappers onto a system and configure default hosts.allow/hosts.deny files

include tcpwrappers

Install tcpwrappers and ensure that the version is always the most recent package available

class { 'tcpwrappers':
  package_ensure => 'latest',
}

or via hiera:

tcpwrappers::package_ensure: 'latest'

Install tcpwrappers and include 'ALL : ALL' in hosts.deny to block all specifically allowed access

class { 'tcpwrappers':
  default_deny => true,
}

Install tcpwrappers and allow traffic to all services from the localhost IPv4/6 address:

class { 'tcpwrappers':
    allow_localhost_ipv4 => true,
    allow_localhost_ipv6 => true,
}

Install tcpwrappers and allow traffic to sshd from all clients

class{ 'tcpwrappers':
  allow_sshd_all => true,
}

Access rule to allow all clients access to all daemons

tcpwrappers::allow { 'all_all_allow':
  client_list => 'ALL',
  daemon_list => 'ALL',
  order       => '10_all_all_allow',
  comment     => 'Allow all clients access to all daemons',
}

Allow all clients access to the sshd and httpd daemons

tcpwrappers::allow { 'all_sshd_httpd':
  client_list => 'ALL',
  daemon_list => [ 'sshd', 'httpd', ],
  order       => '66_all_sshd_httpd',
  comment     => 'Allow all clients access to sshd and httpd',
}

Allow access to snmpd from two specified client definitions

tcpwrappers::allow { 'example_snmpd':
  client_list => [ '.example.com', '192.168.', ],
  daemon_list => 'snmpd',
  order       => '161_example_snmpd',
  comment     => 'Allow access to snmpd from the example.com domain and IP addresses',
}

Allow traffic to sshd and httpd from the example.com domain

tcpwrappers::allow { 'example_sshd_httpd':
  client_list => [ '.example.com', '192.168.', ],
  daemon_list => [ 'sshd', 'httpd', ],
  order       => '22_example_sshd_httpd',
  comment     => 'Allow traffic to sshd and httpd from the example.com domain and IP addresses',
}

Rule for logging and denying access to sshd from example.com

tcpwrappers::allow { 'example_sshd_deny':
  client_list      => '.example.com',
  daemon_list      => 'sshd',
  order            => '22_example_sshd_deny',
  comment          => 'Log and deny access to sshd from example.com',
  optional_actions => [ 'spawn /bin/echo `/bin/date` access denied>>/var/log/sshd.log', 'DENY', ],
}

Allow access to sshd from example.com except for badactor.example.com

tcpwrappers::allow { 'example_sshd_no_badactor':
  client_list => '.example.com EXCEPT badactor.example.com',
  daemon_list => 'sshd',
  order       => '22_example_sshd_no_badactor',
  comment     => 'Allow traffic to sshd from example.com domain except from badactor.example.com',
}

Allow access to all daemons except vsftd from 192.168. without an action specified

tcpwrappers::allow { 'all_except_vsfptd_192_168':
  client_list      => '192.168.',
  daemon_list      => 'ALL EXCEPT vsftpd',
  optional_actions => '',
  order            => '10_except_vsftpd_192_186',
  comment          => 'Allow access to all daemons except vsftpd from 192.168.',
}

Using the tcpwrappers::allows class to create multiple rules

# node.pp
class { 'tcpwrappers': }
  class { 'tcpwrappers::allows':
    rules => {
      spec_telnet => {
        client_list => 'ALL',
        daemon_list => 'telnet',
        order       => '22_telnet_all',
        comment     => 'Allow all clients access to telnet',
      },
      spec_vsftpd => {
        client_list => 'ALL',
        daemon_list => 'vsftpd',
        order       => '21_vsftpd_all',
        comment     => 'Allow all clients access to vsftpd',
      }
    }
  }
}

Using hiera data to create multiple tcpwrappers rules with the default behavior

 ---
 # node.yaml
  tcpwrappers::allows::rules:
    sshd_all
      client_list: ALL
      daemon_list: sshd
      order: 22_sshd_all
      comment: 'Allow all clients access to sshd'
    vsftpd_all:
      client_list: ALL
      daemon_list: vsftpd
      order: 21_vsftpd_all
      comment: 'Allow all clients access to vsftpd'

Using hiera data to create multiple tcpwrappers rules with a merged hash from multiple files

 ---
 # node.yaml
  tcpwrappers::allows::rules:
    httpd_all:
      client_list: ALL
      daemon_list: httpd
      order: 80_httpd_all
      comment: 'Allow all clients access to httpd'

# common.yaml
lookup_options:
  tcpwrappers::allows::rules:
    merge: hash
tcpwrappers::allows::rules:
    sshd_all
      client_list: ALL
      daemon_list: sshd
      order: 22_sshd_all
      comment: 'Allow all clients access to sshd'

Reference

Generated puppet strings documentation with examples is available from https://millerjl1701.github.io/millerjl1701-tcpwrappers/

The puppet strings documentation is also included in the github repository in the /docs folder.

Public Classes

• tcpwrappers: Main class which installs and configured tcpwrappers. Parameters can be passed via class declaration or hiera.
• tcpwrappers::allows: Class for creating multiple hosts.allow rules via hiera data files or by passing a hash as a parameter directly.

Private Classes

• tcpwrappers::config: Class which performs some initial configuration of tcpwrappers. All behavior is driven using parameters to the main class.
• tcpwrappers::install: Class which performs installation of the tcp_wrappers package. All behavior is driven using parameters to the main class.

Public Defined Types

• tcpwrappers::allow: Creates a hosts.allow concat fragment.

Parameters

The tcpwrappers::init class has the following parameters:

Boolean         $allow_header         = true,
String          $allow_header_source  = "tcpwrappers/allow_header_${::operatingsystem}",
Boolean         $allow_localhost_ipv4 = false,
Boolean         $allow_localhost_ipv6 = false,
Boolean         $allow_sshd_all       = false,
String          $config_dir           = '/etc',
Boolean         $default_deny         = false,
Boolean         $deny_header          = true,
String          $deny_header_source   = "tcpwrappers/deny_header_${::operatingsystem}",
String          $file_allow           = 'hosts.allow',
String          $file_deny            = 'hosts.deny',
String          $package_ensure       = 'present',
String          $package_name         = 'tcp_wrappers',

The tcpwrappers::allow class has the following parameters:

Variant[String,Array[String]]             $client_list,
Variant[String,Array[String]]             $daemon_list,
String                                    $order,
Optional[String]                          $allow_template   = 'tcpwrappers/allow.erb',
Optional[String]                          $comment          = undef,
Optional[Variant[String,Array[String]]]   $optional_actions = 'ALLOW',

The tcpwrappers::allows class has the following parameters:

Hash $rules = {},

Limitations

This module was setup using CentOS 6 and 7 installation and documentation for rules. In time, other operating systems will be added as they have been tested. Pull requests with tests are welcome!

While this module was written to simplify the creation of hosts.allow and hosts.deny rules on a system, no validation of the parameters used to create the rules is done. This is left as an exercise for the reader.

Warning: If this module is applied to a system that already has rules in hosts.allow and hosts.deny specified, they will be removed by the module.

Development

This module has been converted over to using the Puppet Development Kit from a legacy Gemfile setup. Prior to submitting a pull request, run the pdk validate command to ensure that the metadata and puppet manifests are of correct syntax. To specify a specific version of puppet to validate sysntax, run the command pdk validate --puppet-version 5.5.12 which would validate against Puppet 5.5.12.

All new code should have unit tests using rspec-puppet in the spec/classes directory. Once written, the pdk test unit command compiles catalogs for all supported operating systems ensuring that all resources are present in the catalog according the the unit test requirements.

All new functionality should have acceptance tests written using ServerSpec. Beaker is used as the test harness to provision a virtual machine, install puppet, and then configure the virtual machine with the module. If you have vagrant installed, the commands that you would use to run acceptance tests would be:

BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_destroy=no BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_provision=no BEAKER_destroy=no BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_PUPPET_COLLECTION=puppet5 BEAKER_set=centos-6-x64 pdk bundle exec rake beaker

The first command runs acceptance tests against the default node set using the puppet5 collection. The second command add BEAKER_destroy=no to prevent the virtual machine from being destroyed at the end of the run in order to inspect the actual virtual machine. The third command allows you rerun the acceptance tests against the virtual machine without reprovisioning. The last command adds BEAKER_set to change the nodeset away from default to allow for testing other operating systems.

Contributors

To see who is involved with this module, see the GitHub list of contributors or the CONTRIBUTORS document.

2020-06-18 Release 1.2.0

• Add Puppet 6 support
• Convert to PDK 1.18.0

2018-07-24 Release 1.1.2

• PR 1: Added include to manifests, and empty hashse to empty data files
• Clarified private classes by using assert_private() stdlib function
• Updated documentation

2017-11-08 Release 1.1.1

• Added tiered hiera data files to test merge behavior
• Updated README for use of merge behavior instead of default first

2017-11-07 Release 1.1.0

• adds the ability to create multiple rules at once using hiera data files or passing a hash to the tcpwrappers::allows class

2017-11-05 Release 1.0.1

• metadata.json: modded to point project_page to github source instead of documentation pages
• Fixed puppet lint errors
• .travis.yml: updated for new password

2017-11-05 Release 1.0.0

• Installation and configuration of tcpwrappers for RedHat/CentOS 6/7
• Added ability to create access/deny rules using alphanumeric ordered concat fragments
• Created full coverage of spec tests
• Created full coverage of acceptance tests