puppetlabs / puppetlabs-tagmail

Report processor that sends email based on events in reports

tagmail

Table of Contents

1. Module description - What the module does and why it is useful
2. Support
3. Setup - The basics of getting started with tagmail
   • Requirements
   • Beginning with tagmail
4. Usage - Configuration options and additional functionality
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

The tagmail module sends Puppet log messages as email if the log messages relate to resources that have been assigned specific tags. This module provides the same functionality as the tagmail feature that was previously built into Puppet.

The tagmail module is a report processor plugin that lets you sort log messages into email reports by pairing particular tags with particular email addresses. This module replaces Puppet's built-in tagmail feature, which is broken in the JVM-based PE 3.7 and completely removed in PE 3.8 and Puppet 4.0.

Note that version 1.x of the tagmail module supports only Puppet 3.7 to 3.8 and PE 3.7 to 3.8.1. For newer versions of Puppet or PE, you must upgrade to tagmail 2.0. For older versions of Puppet, use Puppet's built-in tagmail feature.

Support

This module is not supported or maintained by Puppet and does not qualify for Puppet Support plans. It's provided without guarantee or warranty and you can use it at your own risk. All bugfixes, updates, and new feature development will come from community contributions. [tier:community]

Setup

Requirements

This module supports Puppet Enterprise and Puppet versions 3.8 or newer. For older versions of Puppet, use Puppet's built-in tagmail feature.

Beginning with tagmail

1. On each Puppet agent, make sure the pluginsync and report settings are enabled. (These settings are normally enabled by default.)

[main]
report = true
pluginsync = true

2. On the Puppet server, include tagmail in the reports setting in the server section:

[server]
tagmap = $confdir/tagmail.conf
reports = puppetdb,console,tagmail

3. If you use anti-spam controls such as grey-listing on your mail server, allowlist Puppet's sending email address to ensure your tagmail reports are not discarded as spam. This setting is controlled by the reportfrom setting in puppet.conf.

4. In the Puppet confdir on your server, create a tagmail.conf file. This file will contain your email transport config options, as well as the tags themselves.

Usage

Tags

Tags let you set context for resources, classes, and defined types. For example, you can assign a tag to all resources associated with a particular operating system, location, or other characteristic. The tag is then included in all log messages related to those resources.

Puppet's loglevels (debug, info, notice, warning, err, alert, emerg, crit, and verbose) can also be used as tags, and the all tag always matches every log message. To learn more about tags, see tags in the Puppet Language docs.

Configure tagmail.conf

To configure the tagmail module, edit the tagmail.conf file you created in Step 4 above. This file is located in your Puppet confdir. The tagmail.conf should be formatted as an ini file.

1. Open tagmail.conf in your text editor and add create [transport] and [tagmap] sections.

2. In the [transport] section, specify either:

   • sendmail, with a path to your sendmail binary (by default, /usr/sbin/sendmail).
   • smtpserver, smtpport, and smtphelo. If you do not specify smtpserver, tagmail defaults to using sendmail.

3. In the [tagmap] section , specify tags and email addresses. Each line should include both:

   • A comma-separated list of tags, ending with a colon
   • A comma-separated list of email addresses to receive log messages for the listed tags. Optionally, exclude any given tag by prefix it with an exclamation mark.

For example, this tagmail.conf sends all log messages to [email protected], and all messages from webservers that are not also mailservers to [email protected] and to [email protected]:

[transport]
reportfrom = [email protected]
smtpserver = smtp.example.org
smtpport = 25
smtphelo = example.org

[tagmap]
all: [email protected]
webserver, !mailserver: [email protected], [email protected]

If you specify sendmail instead of smtpserver, it might look like:

[transport]
reportfrom = [email protected]
sendmail = /usr/sbin/sendmail

[tagmap]
all: [email protected]
webserver, !mailserver: [email protected], [email protected]

Limitations

For an extensive list of supported operating systems, see metadata.json

This module should be used only if you're using the JVM on the Puppet server. For older versions of Puppet, or if using the legacy Puppet server on Apache/Rack/Passenger, use Puppet's built-in tagmail feature.

Development

Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

For more information, see our module contribution guide.

To see who's already involved, see the list of contributors.

puppetlabs-tagmail's Issues

Deprecated Object Warning

Describe the Bug

Seeing the below logged in the system logs

May 3 00:31:32 PUPPETLV01L-HU puppetserver[718109]: /etc/puppetlabs/code/environments/production/modules/tagmail/lib/puppet/reports/tagmail.rb:207: warning: deprecated Object#=~ is called on Array; it always returns nil

Expected Behavior

Not log / remove the deprecated content before it's removed

Steps to Reproduce

Steps to reproduce the behavior:

1. Check the logs

Environment

• Version 4.1.0
• Platform RHEL8

Additional Context

Originally logged at https://tickets.puppetlabs.com/browse/MODULES-11428, but that's no longer accessible and I've been unable to locate where it was migrated too. So have raising again.

tagmail ignores catalog failures

If catalog compilation fails, tagmail ignores the failure, IMHO, this should emit a report

unable to send reports

I am using this module to send reports however I'm having an issue with one of our nodes running Fedora 28. Running puppet agent -t results in the following error message.

Error: Could not send report: undefined method `split' for :message:Symbol

Does anybody know what would cause this or how to resolve it? Here is the package information for ruby and puppet on this node.

[root@testvm ~]# rpm -qi puppet ruby
Name        : puppet
Version     : 4.10.10
Release     : 1.fc28
Architecture: noarch
Install Date: Wed 28 Nov 2018 09:34:21 AM EST
Group       : System Environment/Base
Size        : 5323470
License     : ASL 2.0
Signature   : RSA/SHA256, Thu 15 Mar 2018 02:57:30 PM EDT, Key ID e08e7e629db62fb1
Source RPM  : puppet-4.10.10-1.fc28.src.rpm
Build Date  : Thu 15 Mar 2018 02:43:03 PM EDT
Build Host  : buildvm-armv7-04.arm.fedoraproject.org
Relocations : (not relocatable)
Packager    : Fedora Project
Vendor      : Fedora Project
URL         : http://puppetlabs.com
Bug URL     : https://bugz.fedoraproject.org/puppet
Summary     : A network tool for managing many disparate systems
Description :
Puppet lets you centrally manage every important aspect of your system using a
cross-platform specification language that manages all the separate elements
normally aggregated in different files, like users, cron jobs, and hosts,
along with obviously discrete elements like packages, services, and files.

Name        : ruby
Version     : 2.5.3
Release     : 94.fc28
Architecture: x86_64
Install Date: Wed 28 Nov 2018 09:34:18 AM EST
Group       : Development/Languages
Size        : 81978
License     : (Ruby or BSD) and Public Domain and MIT and CC0 and zlib and UCD
Signature   : RSA/SHA256, Mon 12 Nov 2018 06:36:53 AM EST, Key ID e08e7e629db62fb1
Source RPM  : ruby-2.5.3-94.fc28.src.rpm
Build Date  : Fri 26 Oct 2018 11:31:20 AM EDT
Build Host  : buildvm-14.phx2.fedoraproject.org
Relocations : (not relocatable)
Packager    : Fedora Project
Vendor      : Fedora Project
URL         : http://ruby-lang.org/
Bug URL     : https://bugz.fedoraproject.org/ruby
Summary     : An interpreter of object-oriented scripting language
Description :
Ruby is the interpreted scripting language for quick and easy
object-oriented programming.  It has many features to process text
files and to do system management tasks (as in Perl).  It is simple,
straight-forward, and extensible.

Where's the manifest to manage tagmail.conf?

I get that this module replaces the legacy built-in equivalent, but shouldn't it also provide a class to manage itself?

puppetserver can't locate tagmail report

It seems puppetserver 5.4.5 on RHEL 7 can't locate tagmail report

puppetlabs-tagmail (v2.4.0)

# grep tagmail /etc/puppetlabs/puppet/puppet.conf 
    reports = puppetdb,tagmail

# grep tagmail /var/log/puppetlabs/puppetserver/puppetserver.log

2018-09-22 16:03:26,672 WARN  [qtp1848950712-63] [puppetserver] Puppet No report named 'tagmail'

Not sure if some step is missing in documentation or module is not compatible with modern puppetserver?

Tagmail with Office365

Hello,

Im using Puppet Enterprise and im trying to use Tagmail with Office365, is there a configuration for this?
Or can it only be with SSL, if so, how?

Thanks

special classification of `--noop` runs

I use tagmail as my sole monitoring method (with insufficient time to set up PuppetBoard for example). I would like to be able to have my mailed reports sorted into two folders, those for actual changes and those for --noop runs. At present, it seems the only way this is feasible is to have mail rules based on the body text looking for strings like Would have triggered or (noop). Obviously, these are less than reliable as such strings, though unlikely, could occur with say, a file resource being managed. It would be very useful if the mail's $SUBJECT could provide such a hint.

Dead link in README

In the "Description" section there is a link to "report processor" (https://docs.puppetlabs.com/guides/reporting.html) that is dead.

compatibility with Puppet 8

Describe the Bug

I wasn't ready to make the move to Puppet 8 yet, however, my yum repository mirror mistakenly showed puppetserver-8.0.0-1.el8.noarch.rpm and a yum update updated the puppet version.

Expected Behavior

tagmail should run with Puppet 8

Steps to Reproduce

Steps to reproduce the behavior:

1. Install Puppet 8 RPM on CentOS 8 Stream
2. Logs will show an error:

2023-04-26T10:20:33.989-04:00 ERROR [qtp277425324-72] [puppetserver] Puppet Could not autoload puppet/reports/tagmail: no such file to load -- net/smtp
org/jruby/RubyKernel.java:1057:in `require'
uri:classloader:/META-INF/jruby.home/lib/ruby/stdlib/rubygems/core_ext/kernel_require.rb:85:in `require'
/etc/puppetlabs/code/environments/production/modules/tagmail/lib/puppet/reports/tagmail.rb:6:in `<main>'
org/jruby/RubyKernel.java:1091:in `load'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/util/autoload.rb:78:in `load_file'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/util/autoload.rb:182:in `load'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/util/instance_loader.rb:54:in `block in loaded_instance'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/concurrent/lock.rb:10:in `synchronize'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/util/instance_loader.rb:49:in `loaded_instance'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/util/instance_loader.rb:27:in `block in instance_load'
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/indirector/report/processor.rb:52:in `block in processors'

Environment

• Version 8.0.0
• Platform CentOS 8 Stream
• mod 'puppetlabs-tagmail', '4.1.0'