Version information
This version is compatible with:
- Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
- Puppet >= 7.0.0 < 9.0.0
- , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'philippeganz-stunnel', '3.1.1'
Learn more about managing modules with a PuppetfileDocumentation
stunnel
Table of Contents
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
- https://www.stunnel.org/
- http://en.wikipedia.org/wiki/Stunnel
- http://en.wikipedia.org/wiki/Secure_Sockets_Layer
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",
}
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 7 with modern dependencies and good practices.
Please do contribute if you're missing some features or create an issue.
Contributors
- Yann Vigara
- Ross Williams
- John Cooper
- Francois Gouteroux
- Stephen Hoekstra
- mjs510
- Olivier Fontannaud
- Philippe Ganz
Reference
Table of Contents
Classes
stunnel
: Basic Stunnel config. Installs the packages and creates essential directories.
Defined types
stunnel::connection
: Establishes a new stunnel connection.
Classes
stunnel
Basic Stunnel config. Installs the packages and creates essential directories.
- Since 0.0.0
Examples
Basic usage
include stunnel
Parameters
The following parameters are available in the stunnel
class:
bin_name
bin_path
cert_dir
config_dir
log_dir
packages
packages_ensure
packages_provider
pid_dir
user
group
bin_name
Data type: Optional[String]
Name of the stunnel executable.
Default value: undef
bin_path
Data type: Optional[Stdlib::Absolutepath]
Path to the directory containing the stunnel executable.
Default value: undef
cert_dir
Data type: Optional[Stdlib::Absolutepath]
Path to the directory containing the certificates.
Default value: undef
config_dir
Data type: Optional[Stdlib::Absolutepath]
Path to the directory containing the configuration files.
Default value: undef
log_dir
Data type: Optional[Stdlib::Absolutepath]
Path to the directory containing the output files.
Default value: undef
packages
Data type: Optional[Array]
List of packages to install.
Default value: undef
packages_ensure
Data type:
Optional[Enum[
'present',
'latest'
]]
If packages should be updated or not.
Default value: undef
packages_provider
Data type: Optional[String]
Provider to use to install the packages. Mandatory on Windows.
Default value: undef
pid_dir
Data type: Optional[Stdlib::Absolutepath]
Path to the directory containing the pid file. Linux only.
Default value: undef
user
Data type: Optional[String]
User that will own the files and run the service.
Default value: undef
group
Data type: Optional[String]
Group that will own the files and run the service.
Default value: undef
Defined types
stunnel::connection
Establishes a new stunnel connection.
-
Since 0.0.0
-
See also
Examples
Basic usage
include stunnel
stunnel::connection {'my_tunnel':
active => true,
enable => true,
client => true,
accept => 32000,
protocol => connect,
protocol_host => 'remote_url:564',
connect => 'my_proxy:8080',
debug_level => 5,
log_file => "${stunnel::log_dir}/my_tunnel.log",
}
Parameters
The following parameters are available in the stunnel::connection
defined type:
- Reference
- Table of Contents
- Classes
- Defined types
stunnel::connection
- Examples
- Parameters
stunnel_name
ensure
manage_service
active
enable
client
accept
protocol
protocol_host
connect
failover
ca_file_path
ca_file_content
ca_dir_path
cert_file_path
cert_file_content
key_file_path
key_file_content
timeoutidle
openssl_options
socket_options
service_options
debug_level
log_file
global_options
stunnel_name
Data type: String
Name of the stunnel connection.
Default value: $name
ensure
Data type: Enum['present','absent']
Wheather the connection should be created or deleted.
Default value: 'present'
manage_service
Data type: Boolean
Wheather or not a service should be created for this connection.
Default value: true
active
Data type: Optional[Boolean]
Weather the service should be running or not. Needs manage_service to be true.
Default value: undef
enable
Data type:
Optional[Variant[
Boolean,
Enum['mask']
]]
Weather the service should be set to run at boot. Needs manage_service to be true.
Default value: undef
client
Data type: Optional[Enum['yes','no']]
Client mode (remote service uses TLS).
Default value: undef
accept
Data type:
Optional[Variant[
String,
Integer[0]
]]
Accept connections on specified address. If no host specified, defaults to all IPv4 addresses for the local host. To listen on all IPv6 addresses use: :::PORT
Default value: undef
protocol
Data type: Optional[String]
Application protocol to negotiate TLS. This option enables initial, protocol-specific negotiation of the TLS encryption. The protocol option should not be used with TLS encryption on a separate port. See official stunnel documentation for supported protocol.
Default value: undef
protocol_host
Data type: Optional[String]
Host address for the protocol negotiations. For the 'connect' protocol negotiations, protocolHost specifies HOST:PORT of the final TLS server to be connected to by the proxy. The proxy server directly connected by stunnel must be specified with the connect option. For the 'smtp' protocol negotiations, protocolHost controls the client SMTP HELO/EHLO value.
Default value: undef
connect
Data type:
Optional[Variant[
String,
Array[String]
]]
Connect to a remote address. If no host is specified, the host defaults to localhost. Multiple connect options are allowed in a single service section. If host resolves to multiple addresses and/or if multiple connect options are specified, then the remote address is chosen using a round-robin algorithm.
Default value: undef
failover
Data type: Optional[Enum['rr','prio']]
Failover strategy for multiple "connect" targets. rr round robin - fair load distribution prio priority - use the order specified in config file default: prio
Default value: undef
ca_file_path
Data type: Optional[Stdlib::Absolutepath]
Load trusted CA certificates from a file. The loaded CA certificates will be used with the verifyChain and verifyPeer options.
Default value: undef
ca_file_content
Data type: Optional[String]
If specified, will populate the CA file @ca_file_path. If this path is not specified, it will populate a default CA file in cert_dir/stunnel_name_CA.pem
Default value: undef
ca_dir_path
Data type: Optional[Stdlib::Absolutepath]
Load trusted CA certificates from a directory. The loaded CA certificates will be used with the verifyChain and verifyPeer options. Note that the certificates in this directory should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the DER encoded subject of the cert. The hash algorithm has been changed in OpenSSL 1.0.0. It is required to c_rehash the directory on upgrade from OpenSSL 0.x.x to OpenSSL 1.x.x or later. CApath path is relative to the chroot directory if specified.
Default value: undef
cert_file_path
Data type: Optional[Stdlib::Absolutepath]
Certificate chain file name. The parameter specifies the file containing certificates used by stunnel to authenticate itself against the remote client or server. The file should contain the whole certificate chain starting from the actual server/client certificate, and ending with the self-signed root CA certificate. The file must be either in PEM or P12 format. A certificate chain is required in server mode, and optional in client mode. This parameter is also used as the certificate identifier when a hardware engine is enabled.
Default value: undef
cert_file_content
Data type: Optional[String]
If specified, will populate the cert file @cert_file_path. If this path is not specified, it will populate a default cert file in cert_dir/stunnel_name_cert.pem
Default value: undef
key_file_path
Data type: Optional[Stdlib::Absolutepath]
Private key for the certificate specified with cert option. A private key is needed to authenticate the certificate owner. Since this file should be kept secret it should only be readable by its owner. On Unix systems you can use the following command: chmod 600 keyfile This parameter is also used as the private key identifier when a hardware engine is enabled. default: the value of the cert option
Default value: undef
key_file_content
Data type: Optional[String]
If specified, will populate the key file @key_file_path. If this path is not specified, it will populate a default key file in cert_dir/stunnel_name.key
Default value: undef
timeoutidle
Data type: Optional[Integer[0]]
Time to keep an idle connection.
Default value: undef
openssl_options
Data type: Optional[Array[String]]
OpenSSL library options. The parameter is the OpenSSL option name as described in the SSLCTX_set_options(3ssl) manual, but without SSL_OP prefix. stunnel -options lists the options found to be allowed in the current combination of stunnel and the OpenSSL library used to build it. Several option lines can be used to specify multiple options. An option name can be prepended with a dash ("-") to disable the option. Use sslVersionMax or sslVersionMin option instead of disabling specific TLS protocol versions when compiled with OpenSSL 1.1.0 or later.
Default value: undef
socket_options
Data type: Optional[Array[String]]
Set an option on the accept/local/remote socket. The values for the linger option are l_onof:l_linger. The values for the time are tv_sec:tv_usec.
Default value: undef
service_options
Data type:
Optional[Hash[
String,
Data
]]
Any supported service option currently not available in this define.
Default value: undef
debug_level
Data type: Optional[Integer[0,7]]
Debugging level. Level is a one of the syslog level names or numbers emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6), or debug (7). All logs for the specified level and all levels numerically less than it will be shown. The default is notice (5). While the debug = debug or debug = 7 level generates the most verbose output, it is only intended to be used by stunnel developers. Please only use this value if you are a developer, or you intend to send your logs to our technical support. Otherwise, the generated logs will be confusing.
Default value: undef
log_file
Data type: Optional[Stdlib::Absolutepath]
Append log messages to a file. /dev/stdout device can be used to send log messages to the standard output (for example to log them with daemontools splogger).
Default value: undef
global_options
Data type:
Optional[Hash[
String,
Data
]]
Any supported global option currently not available in this define.
Default value: undef
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[3.1.1] - 2024-05-17
Changed
- Upgrade PDK to version 3.2.0
[3.1.0] - 2024-05-03
Added
- Add Puppet 8 validations
Changed
- Add support for RHEL 9, Ubuntu 24, Debian 10, 11 & 12
- Add support for Puppet 8
- Upgrade to PDK 3.0.1
Removed
- Drop support for Debian 7 & 8
Fixed
- Services are now correctly notified on cert changes
- Ensure absent now correctly removes the service on linux
[3.0.1] - 2023-07-17
Fixed
- New release for Puppet Forge
[3.0.0] - 2023-07-14
Added
- Support for Windows platform
- Puppet 7 support
- Hiera 5 data
- PDK stack for syntax validation and unit testing
Changed
- Stunnel class has a new interface to tune configuration
- Tun define has been renamed to connection with following new features
- New interface
- OS service management
- Certificate as content or path
- Stunnel config template has been rewritten in epp
Removed
- Certificate concatenation functionnality
- Config class has been moved to init class
- Data class has been moved to hiera 5 data
- Install class has been moved to init class
[2.2.0] - 2016-04-08
- stunnel::tun options parameter now handles an array for multiple options (mjs510)
- support uninstalling stunnel::tun resources (mjs510)
- update documentation to show disabling of SSLv3 by default (mjs510)
- fix: make cert param optional if client == true (mjs510)
- fix: actually use a custom stunnel::tun template if provided (albustax)
- fix: anchor regex pattern validating failover param (mjs510)
[2.1.1] - 2015-02-19
- stop testing puppet 3.3 and 3.4, test 3.6 and 3.7 (with and w/o future parser)
- fix syntax error in metadata.json causing puppet to fail
[2.1.0] - 2015-02-19
- only install lsb-base on debian based systems (kronos-pbrideau)
- allow management of tunnel service (kronos-pbrideau)
- add failover support (shoekstra)
- only fill in "options" config key if present (mighq)
- preserve order of options hash to prevent unnecessary changes (mighq)
- add support for global_opts (choffee)
- add native support for CAFile option per-tunnel
[2.0.0] - 2014-09-17
- convert string representations of booleans into valid booleans (#13,14) (fgouteroux)
- sort options in the tun file to prevent constant puppet change notifications (choffee)
[1.2.0] - 2014-05-08
- match stunnel defaults w/debug=5 (#8)
- add parameter to specify location of output (logging) (#8)
- add global_opts and service_opts parameters to stunnel::tun to allow specifying additional global and service parameters (#8)
- bugfix: properly implement timeoutidle (#9)
[1.1.1] - 2014-03-31
- issue #6 : improved README documentation (ross-williams)
[1.1.0] - 2014-03-20
- issue #5 : add parameter to setup client tunnels
[1.0.1] - 2014-03-17
- Ensure lsb is installed
- bugfix: we weren't installing the right package on Debian systems
[1.0.0] - 2013-08-26
- Debian/Ubuntu support (yvigara)
[0.0.2] - 2013-08-16
- Added initscript for each tunnel
- moved away from multi-services per tunnel
- moar examples!
[0.0.1] - 2013-08-12
- Initial Release
Dependencies
- puppetlabs/chocolatey (>= 6.0.0 < 9.0.0)
- puppetlabs/powershell (>= 5.0.0 < 7.0.0)
- puppetlabs/pwshlib (>= 0.10.2 < 2.0.0)
- puppetlabs/stdlib (>= 7.0.0 < 10.0.0)
- voxpupuli/systemd (>= 4.0.0 < 8.0.0)
The MIT License (MIT) Copyright (c) 2013-2016 The Regents of the University of California Copyright (c) 2023-2024 Philippe Ganz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.