Some global options like "socket" and "engineCtrl" can be specified more than once but the module does not support that.

I thought that adding the option of setting a global option to an array then doing the below in the template might work. ( This is just ruby so translating it to erb first obviously.) Does that sound sane?

global_opts = { "a"=> "b", "c"=>["d","b"]}

global_opts.sort.map do |name, value| 
    if value.kind_of?(Array)
        for val in value do
            puts name + " " + val
        end
    else
      puts name + " " + value
    end
end

setuid and setgid global options should be overridable, and should probably not default to root.

Although you have this nice method for combining certs with the key, it is also possible to specify the cert and key separately in stunnel. This should also be an allowable configuration.

The file /etc/stunnel/conf.d/mysql_stunnel.conf generated by
arusso/puppet-stunnel contains the following line for me:

output = /var/log/stunnel/mysql_stunnel.log

However, stunnel is definitely running (works OK) and when I visit it, I find:

-rw-r----- 1 root root 0 Mar 17 14:39 mysql_stunnel.log

Empty!

So did a bit of Googling and found this:

"Ok, I found the solution to the logging problem.
Because stunnel in running in a chroot environment
(set as /var/run/stunnel) the logging parameter /var/log/stunnel.log was invalid.
Therefore changing it to just "stunnel.log" fixed the issue and now the
logs appear in the folder "/var/run/stunnel"
https://bbs.archlinux.org/viewtopic.php?id=101866

I haven't tried this fix yet.

I went and had a look and my configuration doesn't include any parameter for
the logfile:

stunnel::tun { 'mysql_stunnel':
accept => ...
connect => ...
options => ...
cert => ...
client => ...
}

so it's not clear to me whether I can even set the output parameter from within Puppet.

I don't really know what's going on inside arusso/puppet-stunnel.
What can I do to get a logfile generated?

Ross

PS: The documentation doesn't include a list of parameters. If you provide a comprehensive list, and I find the time, I'll document them.

Aaron,

I have written some documentation for your arusso/puppet-stunnel module.

I think it's a very useful module, and I'd like to contribute by
providing documentation that will help others to use your module.

Ross Williams

stunnel Module

This is an stunnel module that provides support for multiple tunnels, each with
its own initscript.

What Is stunnel?

stunnel is software that enables you to add an SSL (Secure Sockets Layer) to an existing TCP
service, re-presenting the service on a different TCP port, but wrapped in SSL. stunnel
also allows you to create a secure tunnel between two different computers so that a TCP service
that is present on one computer appears on the other computer. This allows you to securely
split onto two computers, a TCP client and server that are currently working on a single
computer, without having to reconfigure either the client or the server.

stunnel is a system service that is automatically re-established if the tunnel software
crashes. This makes it more robust than a manually-created SSH tunnel.

How To Generate A Certificate

In order to create a tunnel using stunnel, you must first create a digital
certificate. This can be done using the shell openssl command
(See http://www.openssl.org/). Here is an example:

openssl genrsa -out key.pem 2048
openssl req -new -x509 -key key.pem -out cert.pem -days 1095
    Country: AU
    State: South Australia
    Locality: Adelaide
    Organisation: Megacorp Pty Ltd
    Common Name: db.megacorp.com
    Email Address: [email protected]
cat key.pem cert.pem >> stunnel.pem

For more information, see
https://www.digitalocean.com/community/articles/how-to-set-up-an-ssl-tunnel-using-stunnel-on-ubuntu
or go crazy Googling.

How To Use Puppet To Install A Certificate File

Install the .pem file in the Files directory of your Puppet module. You can then
instruct Puppet to install it anywhere you like. Here is an example of how to use
Puppet to install it in the /etc/ssl/certs directory:

file { '/etc/ssl/certs/mysql_stunnel.pem':
    ensure => 'file',
    owner  => 'root',
    group  => 'root',
    mode   => 700,
    source  => 'puppet:///modules/mymodule/mysql_stunnel.pem',
    before  => Stunnel::Tun['mysql_stunnel'],
}

The before attribute ensures that the `.pem' file is present before
Puppet attempts to create a tunnel.

Examples

Example: Adding an SSL Front End Within A Single Computer

This example shows how to use stunnel to take an unencrypted imap email
service on TCP port 143, and present it as an encrypted imap email service
on TCP port 993. The encrypted connection employs the digital certificate
at /etc/certs/stunnel-imaps.pem. Here is the Puppet configuration to do this:

include stunnel
stunnel::tun { 'imaps':
  accept  => '993',
  connect => 'localhost:143',
  options => 'NO_SSLv2',
  cert    => '/etc/certs/stunnel-imaps.pem',
  client  => false,
}

Example: Tunnelling A TCP Port Between Computers

This example shows how to create an stunnel tunnel between two different computers.
In particular, this example shows the common case of creating a secure connection
between a MySQL client on one computer (the "client computer") and a MySQL server on a
second computer (the "server computer"). However, you should be able to adapt the
example to work for any non-MySQL TCP connection.

In this example, an stunnel service is installed on the client computer and also
separately on the server computer. The same .pem certificate file is provided
to each of them. The two services communicate with each other to establish the
connection from a port on the client computer to a port on the server computer.

In this example, a MySQL client connects to the MySQL server by connecting to TCP port
3306 on the client computer, just as if the MySQL server were running on the client
computer. The stunnel client service on the client computer then accepts the connection
and connects to TCP port 3307 on the server computer using an encrypted protocol that
employs the certificate in the .pem file at each end. On the server computer, an stunnel
server service accepts the connection to TCP port 3307 and connects to TCP port 3306 on the
server computer where the MySQL database server is waiting to accept the connection.
The result is that the client thinks that the server is on its computer, and the server
thinks that the client is on its computer.

For the purposes of this example, we assume that the same .pem certificate file
has been installed at

/etc/ssl/certs/mysql_stunnel.pem

on both the client and the server computers. See an earlier section for how to generate
a certificate file.

To create the tunnel, we install an stunnel client service on the client computer
and an stunnel server service on the server computer. Here is the Puppet configuration
to establish the stunnel service on the client computer. This configuration should
only be applied to the client computer. Substitute the name, or IP address, of your
server computer for db.domain.com.

include stunnel
stunnel::tun { 'mysql_stunnel':
  accept  => '3306',               # The stunnel client will listen to this port.
  connect => "db.domain.com:3307", # The stunnel client will connect to this port.
  options => 'NO_SSLv2',
  cert    => '/etc/ssl/certs/mysql_stunnel.pem',
  client  => true,
}

Here is the Puppet configuration to establish the stunnel service on the server computer.
This configuration should only be applied to the server computer.

include stunnel
stunnel::tun { 'mysql_stunnel':
  accept  => '3307', # The stunnel server will listen to this port.
  connect => '3306', # The stunnel server will connect to this port.
                     # Note: I tried 'localhost:3306', but the 'localhost' stopped it from working.
  options => 'NO_SSLv2',
  cert    => '/etc/ssl/certs/mysql_stunnel.pem',
  client  => false,
}

In this two-computer example, the client attribute distinguishes an
stunnel client installation from an stunnel server installation. This is critical
because stunnel clients and servers do asymmetric things.
The stunnel client on the client computer accepts
MySQL connections on TCP port 3306 and creates an encrypted connection to TCP port 3307 on
the server computer. The stunnel server on the server computer accepts the encrypted
TCP connection on TCP port 3307 and has an encrypted conversation. It connects to
local TCP port 3306 and transmits the decrypted data.

A significant advantage of using stunnel in this way is that neither the
MySQL client on the client computer, nor the MySQL server on the server
computer need to be configured any differently to make it work. This means
that if you have a MySQL client process and a MySQL server process working
on a single computer, you can use stunnel to split them over two computers
without compromising security.

Multiple Clients

In the two-computer example above, the solution is presented as an stunnel
client/server pair as if they are bound together. In fact, stunnel clients
and servers operate independently as clients and servers. This means that
you can have several different client computers, each configured with an stunnel
client as shown above, and each connecting to the same server computer running
an stunnel server.

Multiple Tunnels

So long as you provide a distinct resource name (mysql_stunnel in the above
examples) and use distinct TCP ports for each tunnel, you can use this Puppet
package to create as many tunnels as you like, with a single computer
implementing clients and servers for several different tunnels. Just
declare a different stunnel::tun resource for each stunnel client or server.

Service Notification

This stunnel Puppet package restarts the stunnel service if a configuration
change has been made.

stunnel Generated Configuration Files

The package installs a configuration file at:

/etc/stunnel/conf.d/mysql_stunnel.conf

where mysql_stunnel is the name of your stunnel::tun resource as above.

This Puppet package also generates an init service configuration script at:

/etc/init.d/stunnel-mysql_stunnel

where stunnel-mysql_stunnel is the name of your stunnel::tun resource
with stunnel- prepended to it.

stunnel Status

Once you've established your stunnel, you can inspect its state using the
following shell commands:

/etc/init.d/stunnel-mysql_stunnel status
/etc/init.d/stunnel-mysql_stunnel start
/etc/init.d/stunnel-mysql_stunnel restart
/etc/init.d/stunnel-mysql_stunnel stop

where stunnel-mysql_stunnel is the name of your stunnel::tun resource
with stunnel- prepended to it.

Installation Errors

If you get the error:

Error: Could not install module 'arusso-stunnel' (latest: v1.0.0)
    Installation would overwrite /etc/puppet/modules/stunnel
    Currently, 'puppetlabs-stunnel' (v0.0.1) is installed to that directory
    Use `puppet module install --target-dir <DIR>` to install modules elsewhere
    Use `puppet module install --force` to install this module anyway

then uninstall the Puppet stunnel model and install the arusso one as follows:

puppet module uninstall stunnel
puppet module install arusso-stunnel

Certificates

stunnel is picky about the certs. You can find more information about it
here in the CERTIFICATES
section.

If you don't want to mess with rebuilding your cert each time the certs you base
it off of get updated, you can use the stunnel::cert class to your benefit:

stunnel::cert { 'imaps':
  components => [ '/etc/pki/tls/private/private.key',
                  '/etc/pki/tls/certs/public.crt' ],
}

This will generate a cert /etc/stunnel/certs/imaps.pem that is the
concatenation of the $components array provided, with a single line in between
each certificate to make stunnel happiest.

Since by default, the cert parameter looks for certs that match the service
name in the /etc/stunnel/certs/ directory, we can omit the cert parameter
if we use the stunnel::cert class. Here's a full example:

include stunnel
stunnel::tun { 'imaps':
  accept   => '993',
  connect  => '143',
  options  => 'NO_SSLv2',
}

stunnel::cert { 'imaps':
  components => [ '/etc/pki/tls/certs/public-cert.crt',
                  '/etc/pki/tls/private/private.key' ],
}

References

https://www.stunnel.org/

http://en.wikipedia.org/wiki/Stunnel

http://en.wikipedia.org/wiki/Secure_Sockets_Layer

https://www.digitalocean.com/community/articles/how-to-set-up-an-ssl-tunnel-using-stunnel-on-ubuntu 

License

See LICENSE file

Copyright

Copyright © 2013 The Regents of the University of California

Contributors:

Yann Vigara

• Debian/Ubuntu support

Ross Williams

• Documentation.

Contact

Aaron Russo [email protected]

Support

Please log tickets and issues at the
Projects site

On minimal systems, ruby may not be installed. Our helper script depends on ruby existing, but our module does not attempt to install ruby (since it was assumed to be installed, as was safe in the past).

In the short term, documenting the Ruby requirement seems reasonable and is what other modules appear to do.

Longer term, the better solution may be to re-write the script into something that is more portable. I'm not sure if it's safe to assume Python is present everywhere, but if it is that would probably be my preference. Otherwise, we should look at doing this with Bash.

Hi the init scripts use /var/lock/subsys which does not always exists. On Ubuntu I don't think that is used.

Could you add something like

[ -d /var/lock/subsys ] || mkdir -p /var/lock/subsys

Thanks

john

Trying to install a tunnel on jessie gives the following:

Error: Execution of '/bin/systemctl enable stunnel-SMTP' returned 1: Synchronizing state for stunnel-SMTP.service with sysvinit using update-rc.d...
Executing /usr/sbin/update-rc.d stunnel-SMTP defaults
insserv: warning: script 'stunnel-SMTP' missing LSB tags and overrides
Executing /usr/sbin/update-rc.d stunnel-SMTP enable
update-rc.d: error: stunnel-SMTP Default-Start contains no runlevels, aborting.
Error: /Stage[main]/Ut_mail_server/Stunnel::Tun[SMTP]/Service[stunnel-SMTP]/ensure: change from stopped to running failed: Execution of '/bin/systemctl enable stunnel-SMTP' returned 1: Synchronizing state for stunnel-SMTP.service with sysvinit using update-rc.d...
Executing /usr/sbin/update-rc.d stunnel-SMTP defaults
insserv: warning: script 'stunnel-SMTP' missing LSB tags and overrides
Executing /usr/sbin/update-rc.d stunnel-SMTP enable
update-rc.d: error: stunnel-SMTP Default-Start contains no runlevels, aborting.

Same configuration works fine for ubuntu. I'll try to troubleshoot further to see if I can find a workaround and will send a PR if I find one.

The pid_dir variable set in data.pp for Debian is:

    /Debian/: {
      $package = [ 'stunnel4', 'lsb-base' ]
      $service = 'stunnel'
      $bin_name = 'stunnel4'
      $bin_path = '/usr/bin'
      $config_dir = '/etc/stunnel'
      $pid_dir = '/var/run'
      $conf_d_dir = '/etc/stunnel/conf.d'
      $cert_dir = '/etc/stunnel/certs'
      $log_dir = '/var/log/stunnel4'
      $setgid = 'root'
      $setuid = 'root'

The /var/run directory is the right place, (although it should be /run now days), but the stunnel4 user that the stunnel runs as is unable to write to that directory a pid file:

May 08 17:23:33 systemd[1]: stunnel-mysqls.service: PID file /var/run/stunnel-mysqls.pid not readable (yet?) after start: No such file or directory

That is because of the permissions of the directory only allows root to write to the directory:

drwxr-xr-x 23 root root 760 May  8 15:27 /run

The debian package 'stunnel4' makes a directory called stunnel4 in /run that is owned by the stunnel4 uid/gid for this pid files:

drwxr-xr-x 2 stunnel4 stunnel4 60 May  8 17:57 /run/stunnel4/

I don't mean to hijack the arusso/puppet-stunnel repo issue tracker, but I cannot seem to find the git repo for http://forge.puppetlabs.com/arusso/ssl. The project link is https://github.com/arusso23/puppet-ssl which results in the wonderful GitHub 404 page. Is the repo available anywhere?

In tun.erb, there is this:

# This file managed by Puppet
<% if @cert_real != '' -%>
cert = <%= @cert_real %>
<% end -%>
<% if @cafile_real != '' -%>
CAfile = <%= @cafile_real %>
<% else -%>
# CAfile = /path/to/cafile.crt
<% end -%>

however, in stunnel4(8) it explicitly details which options are valid global options, and which options are service-specific options (have to occur underneath a [service name] block), and the cert and CAfile options are only specified under the SERVICE-LEVEL OPTIONS section.

If you have to rotate your certificates (imagine heartbleed or similar), your key, or your CA file, the stunnel service must be restarted. The module as it is now does not handle this possibility.

Some tunnels configurations require the usage of a CAfile, please add support for it.

Hello, I am using this module in a RHEL 7 environment in targeted/enforcing mode. The default mode for the file resource in config.pp is causing a problem with this setup, and stunnel cannot start in enforcing mode:

file { $stunnel_dirs:
    ensure => directory,
    owner  => 'root',
    group  => 'root',
    mode   => '0555',
  }

$stunnel_dirs includes the log directory, and without DAC write permission SELinux requires the following:

allow stunnel_t self:capability dac_override;

Would you consider changing the mode to '0755' here? I did confirm that modifying the permissions removes the denial and allows stunnel to start.

Debian uses stunnel4:stunnel4 for uid:gid, but this module sets things to be root:root, this breaks a number of things, such as being able to write to /var/log/stunnel4. This should use the defaults provided by the package, rather than set these to root.

Hello,

When I use the create_resources function (stunnel::tun) with hiera hash, I got the error:
Error 400 on SERVER: "true" is not a boolean. It looks to be a String at [...]/modules/stunnel/manifests/tun.pp:68

Here an example

$stunnel_data = hiera_hash('stunnel::tun', false)
if $stunnel_data {
create_resources('stunnel::tun', $stunnel_data)
}

The hieradata hash

stunnel::tun:
stunnel_test:
accept: '3306'
connect: '192.168.33.10:3307'
options: 'NO_SSLv2'
cert: '/etc/ssl/certs/mysql_stunnel.pem'
client: 'true'

I purpose to add the str2bool function to convert the string to boolean, like:
validate_bool(str2bool($client)).

If you agree, I can make the pull request.

I installed stunnel on CentOS. I haven't got it working yet, but one obstacle I did
encounter was this:

d /etc/init.d
./stunnel-mysql_stunnel
./stunnel-mysql_stunnel: line 21: /lib/lsb/init-functions: No such file or directory

This was fixed by installing the redhat-lsb package:

yum install redhat-lsb

I think it would help CentOS users a lot if you could let them know this. It might
also help to provide the following code to install the package from within Puppet:

package { 'redhat-lsb':
name => 'redhat-lsb',
ensure => installed,
provider => "yum",
}

Thanks for creating this stunnel module. I hope that I can get it working!

Ross

The only examples you have provided set up a tunnel within a single node.

It would be helpful to users of this package to see an example in which
the tunnel spans two different nodes.

I have got all the init.d stuff working now, but am having trouble getting a tunnel
working because I am confused about clients and servers and ports and such.

Ross

I have an stunnel that is connecting to MySQL. I am getting disconnections
that are causing havoc with my web application. Googling, I am finding that there
might be many reasons for this. One reason is that stunnel might be timing out
idle connections after 12 hours which is the default setting of the stunnel parameter called

TIMEOUTidle

It would be good if the arusso/puppet-stunnel module had a parameter
that just passes parameters through to the stunnel config file, so that each
parameter doesn't have to be implemented manually inside arusso/puppet-stunnel.
An example is the "custom_fragment" parameter of the apache::vhost object
which just passes through a block of text.

Ross