Merge branch 'document_nagios_custom_logic' into 'master'
[puppet_stunnel.git] / README
1 Overview
2 ========
3
4 This module manages stunnel4. It installs and configures the software, makes
5 sure it is running, and enables you to create different stunnels.
6
7
8 ! Upgrade Notice !
9 ==================
10
11 Previous versions of this module were not using parameterized classes. If you
12 were using a previous version, you may need to change how you are using the
13 module to accomodate for that. If you were previously setting some stunnel
14 variables before including the class, you will now need to pass those variables
15 to the class as parameters. If you were just simply doing 'include stunnel',
16 then you will not need to change anything.
17
18 Classes
19 =======
20
21 stunnel
22 -------
23
24 This is the main class which brings you stunnel support. You will need to
25 instantiate it by doing the following:
26
27 class { 'stunnel': }
28
29 Class parameters:
30
31 * ensure_version - If this parameter is passed, you can force a particular
32   version of stunnel to be installed, if it is available with your packaging
33   system, for example:
34
35   class { 'stunnel': ensure_version = '3:4.53-1' }
36   
37   If you do not pass this parameter, it will default to just be 'present'.
38
39 * startboot (Debian) - This parameter controls if stunnel should be started at
40   boot or not, if you do not pass this paramter, by default it will be started
41
42 * default_extra (Debian) - This parameter lets you add arbitrary extra text to
43   the bottom of /etc/default/stunnel4, this can be useful to set ulimit for
44   example
45
46
47 Defines
48 =======
49
50 stunnel::service
51 ----------------
52
53 This define lets you setup any number of stunnels, it allows you to pass every
54 stunnel configuration variable (see manifests/server.pp) which will be used to
55 create the /etc/stunnel/${name}.conf file, and then notify the stunnel service
56 so it will restart.
57
58 If you pass $manage_nagios to this define, it will create a nagios::service
59 entry for stunnel_${name} which will watch for the appropriate number processes
60 with that configuration name
61
62 Note that if you need to use some specific logic to decide whether or not to
63 create a nagios service check, you should set $manage_nagios to false, and
64 use stunnel::service::nagios from within your own manifests.
65
66 stunnel::service::nagios
67 ------------------------
68
69 This define creates a nagios service check for a specific tunnel. The resource
70 name should be the name of the tunnel's configuration file without the '.conf'
71 suffix. For example:
72
73     stunnel::service::nagios { 'carpal': }
74
75 The above example would verify that the tunnel defined in
76 `/etc/stunnel/carpal.conf'.
77