stunnel

stunnel

Module Description

This module aims to provide a wrapper around the stunnel software.

It helps you put in place stunnel connections with only a few lines of yaml.

It does not aim at replacing the software nor take ownership for their code.

From the creator's description :

Stunnel is a proxy designed to add TLS encryption functionality to existing clients and servers without any changes in the programs' code. Its architecture is optimized for security, portability, and scalability (including load-balancing), making it suitable for large deployments.

Stunnel uses the OpenSSL library for cryptography, so it supports whatever cryptographic algorithms are compiled into the library. It can benefit from the FIPS 140-2 validation of the OpenSSL FIPS Provider, as long as the building process meets the OpenSSL FIPS 140-2 Security Policy. Our latest Windows installer includes the OpenSSL FIPS Provider.

References

Setup

What puppet-stunnel affects

Depending on the parameter you provide, it might affect system services, system sockets, ports, and some local configuration files for stunnel.

Setup requirements

You need to have the Stunnel software available in your favorite package manager, e.g. Chocolatey on Windows or yum on RHEL.

Beginning with puppet-stunnel

Simply include the module in your control-repo. This will install the necessary piece of software needed to have you up and running with stunnel on your platform.

include stunnel

Usage

All options and possibilities can be found in the REFERENCE file.

Create a client-server connection

Having following layout

(32000) Client (Dynamic range) <--> (1564) Server (27000)

The client would look like this

include stunnel

stunnel::connection {'my_tunnel':
  active        => true,
  enable        => true,
  client        => true,
  accept        => 32000,
  connect       => 'remote_url_or_ip:1564',
  debug_level   => 5,
  log_file      => "${stunnel::log_dir}/my_tunnel.log",
}

and the server like this

include stunnel

stunnel::connection {'my_tunnel':
  active        => true,
  enable        => true,
  accept        => 1564,
  connect       => 'localhost:27000',
  debug_level   => 5,
  log_file      => "${stunnel::log_dir}/my_tunnel.log",
}

Create a client stunnel connecting through a proxy

Now imagine you add a proxy in the middle

(32000) Client (Dynamic range) <--> (8080) Proxy (Dynamic range) <--> (1564) Server (27000)

include stunnel

stunnel::connection {'my_tunnel':
  active        => true,
  enable        => true,
  client        => true,
  accept        => 32000,
  protocol      => connect,
  protocol_host => 'remote_url_or_ip:1564',
  connect       => 'my_proxy:8080',
  debug_level   => 5,
  log_file      => "${stunnel::log_dir}/my_tunnel.log",
}

Securing connections with SELinux, chroot, and FIPS

By enabling $manage_selinux on the base class, the module automatically labels generated ports with stunnel_port_t and chroot directories with stunnel_var_run_t. You can optionally enforce FIPS compliance on specific connections.

class { 'stunnel':
  manage_selinux => true,
  chroot_enable  => true,
}

stunnel::connection { 'secure_tunnel':
  active          => true,
  enable          => true,
  accept          => 9090,
  connect         => 'localhost:8080',
  fips            => true,
}

Limitations

Support for older operating system have not been ported from arusso's version.

This module depends greatly on features implemented by the stunnel team, no warranties on those, you'll have to deal with them if something isn't working as expected.

Development

This module has been forked from arusso (thanks a lot for your work !).

It has been ported to Puppet 8 with strict custom data types, modern dependencies, and aggressive security boundaries.

Please do contribute if you're missing some features or create an issue.