Cookbook Version (opens in a new tab) Build Status (opens in a new tab) OpenCollective OpenCollective License (opens in a new tab)

Chef cookbook to install and configure stunnel


This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit (opens in a new tab) or come chat with us on the Chef Community Slack in #sous-chefs (opens in a new tab).


  • Chef 13

Platform Support

  • Ubuntu 14.04+
  • CentOS 6.9+


An stunnel_connection resource is provided for defining stunnel connections. As a client:

include_recipe 'stunnel'
stunnel_connection 'random_service' do
  connect "#{rnd_srv_node['ipaddress']}:#{rnd_srv_node['random_service']['port']}"
  accept node['random_service']['local_accept_port']
  notifies :restart, 'service[stunnel]'

As a server:

include_recipe 'stunnel::server'
stunnel_connection 'random_service' do
  accept node['random_service']['tunnel_port']
  connect node['random_service']['port']
  notifies :restart, 'service[stunnel]'


Lots of configurable attributes:

default['stunnel']['install_method'] = 'package'  # the other valid option is 'source'
default['stunnel']['packages'] = %w(stunnel4)
default['stunnel']['service_name'] = 'stunnel4'
default['stunnel']['ssl_dir'] = '/etc/ssl'
default['stunnel']['server_ssl_req']  = "/C=US/ST=Several/L=Locality/O=Example/OU=Operations/CN=#{node['fqdn']}/emailAddress=root@#{node['fqdn']}"
default['stunnel']['cert_fqdn'] = node['fqdn']
default['stunnel']['use_chroot'] = false
default['stunnel']['chroot_path'] = "/usr/var/lib/stunnel"
default['stunnel']['pidfile'] = "/tmp/"
default['stunnel']['user'] = "root"
default['stunnel']['group'] = "root"
default['stunnel']['ulimit'] = nil # set to a number to add ulimit setting to init script
default['stunnel']['https']['enabled'] = false
default['stunnel']['https']['accept_port'] = "443"
default['stunnel']['https']['connect_port'] = "81"
default['stunnel']['client_mode'] = true
default['stunnel']['fips'] = nil
default['stunnel']['ssl_version'] = 'all'
default['stunnel']['ssl_options'] = 'NO_SSLv2'
default['stunnel']['socket_tunings'] = %w(l:TCP_NODELAY=1 r:TCP_NODELAY=1)
default['stunnel']['compression'] = nil # zlib
default['stunnel']['debug'] = nil # 3
default['stunnel']['output'] = '/var/log/stunnel.log'
# key value pair mapping for default var file
default['stunnel']['default']['enabled'] = 1
default['stunnel']['default']['files'] = '/etc/stunnel/-.conf'
default['stunnel']['default']['options'] = ''
# certificate/key is needed in server mode and optional in client mode
default['stunnel']['certificate_path'] = nil # /etc/pki/stunnel/cert.pem
default['stunnel']['key_path'] = nil # /etc/pki/stunnel/key.pem


FIPS mode can be enabled or disabled with the attribute ['stunnel']['fips']. A value of nil will omit the "fips" setting from the config file altogether, falling back to the default behavior for that version of stunnel:

  • For 4.x releases FIPS defaults to on if stunnel was compiled with FIPS support.
  • For 5.x releases FIPS defaults to off.

ChefSpec Matchers

A set of ChefSpec matchers is included for unit testing with ChefSpec. These are automatically available when you make this cookbook a dependency in your cookbook's metadata. To illustrate:

Recipe code:

stunnel_connection 'haproxy_ssl' do
  accept    '443'
  connect   '8443'

And the matching spec:

it 'should create stunnel_connection haproxy_ssl' do
  expect(chef_run).to create_stunnel_connection('haproxy_ssl').with(
    accept:  '443',
    connect: '8443'

You can also make assertions for notifying other resources:

it 'should notify stunnel to restart on changes to stunnel_connection[haproxy_ssl]' do
  resource = chef_run.stunnel_connection('haproxy_ssl')
  expect(resource).to notify('service[stunnel]').to(:restart)

A matcher for the delete action is also available:

it 'should delete stunnel_connection haproxy_ssl' do
  expect(chef_run).to delete_stunnel_connection('haproxy_ssl')

Testing Locally

To run the tests, make sure you've got the latest ChefDK (opens in a new tab) along with Vagrant (opens in a new tab) then you can run chef exec kitchen test which will run the entire test suite on all platforms.


This project exists thanks to all the people who contribute. (opens in a new tab)


Thank you to all our backers!


Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

Was this helpful?