Pre-Requisites
- The following article includes two sample scripts for testing zenmail, one in Perl and the other in Python. The Perl version requires the Net-SMTP module, so you will need to make sure this is in place if you choose to test with Perl.
Applies To
- Zenoss 4.0.x
- Zenoss 3.1.x
- Zenoss 3.0.x
- Zenoss 2.5.x
Summary
NOTE: This article is NOT about monitoring email servers using ZenMailTx data collection. This article is about generating device events via the 'zenmail' daemon. Zenoss has the ability to listen for inbound SMTP messages for the purposes of generating events for the devices that send them. This is useful for actively generating events outside of the regular polling interval for devices that are equipped to send SMTP messages in response to conditions. The purpose of this article is to expand on the documentation for the zenmail daemon beyond what exists in the Administration Guide, and to provide some small sample scripts
Procedure
By default, zenmail is not enabled and running with the standard list of Zenoss daemons. This is to prevent a potential port binding conflict, since the default port that zenmail attempts to bind to is TCP port 25 which is likely already in use by a locally running SMTP daemon/MTA on the Zenoss server (Sendmail, Postfix, etc). Before enabling and/or starting zenmail, it's a good idea to generate the zenmail.conf file so that the daemon starts up with the configuration you want it to have instead of loading the defaults for everything.
Creating and configuring daemon-specific options:
As the 'zenoss' user on the Zenoss server command line, issue the following command to generate the initial instance of the zenmail.conf file:
zenmail genconf > $ZENHOME/etc/zenmail.conf
When this configuration file is created, open it in vi (or the text editor of your choice). All lines in this initial configuration file will be commented out, however the values that show up for each directive are the defaults that the daemon would use if it were started. Almost all of these are fine as-is, however there are 3 options at the end of the config that might be changed depending on the environment. These options are:
- listenPort: The default value is 25. If you already have an SMTP listener on port 25, you can change the bind port for zenmail here. Keep in mind, the devices that will be sending SMTP messages will need to have the ability to send to the port you specify here.
- eventseverity: The default for this is '2', which means that events coming in via this daemon will be set to 'Info' as the severity value. Other options are:
1 = Debug
2 = Info
3 = Warn
4 = Error
5 = Critical - listenip: The default for this is '0.0.0.0', which is binding to all local addresses. This can be changed to bind to a specific address, and can be used in conjunction with the 'listenPort' outlined above. For example, if you do already have a local SMTP daemon running on port 25, but bound to a specific interface, you can leave the 'listenPort' for zenmail on '25' but change the listenip to bind it to a separate local interface address.
Configuring Zenoss to control zenmail start/stop actions:
As noted earlier, the zenmail daemon is not included in the list of daemons that fall under the umbrella of the Zenoss control script. There are a couple of approaches to implementing this, depending on how local daemons are being controlled. One of the daemon control options that can be used is by maintaining a list of desired deamons in a $ZENHOME/etc/daemons.txt file. If you have this file in place and are using it to control the daemons that run, you will simply add 'zenmail' to this list. If you do not have this, then the daemons are being controlled by the $ZENHOME/bin/zenoss control script. To have 'zenmail' included as a default daemon you will open this file with the text editor of your choice and, depending on your version of Zenoss, around line# 69 will be a line where 'zenmail' is commented out among a list of daemons as follows:
#C="$C zenmail"
You will remove the '#' (pound/hash) comment character, and maintain the indentation to fall in line with the rest of the daemon list. When this is saved, the zenmail will be included in the list of daemons returned when zenoss stop, zenoss start, and zenoss status are run.
Behavior:
Incoming SMTP messages that are handled by zenmail are processed as follows:
- 'To' field - Zenoss drops this information entirely since it's not needed for the event to be created, so the messages can be addressed to any user at any domain.
- 'From' field - Zenoss drops the '@' and everything to the left of it. Everything in the From address that's to the right of the '@' is used to determine the target device to generate the event for. Once Zenoss has parsed out the 'from' information to the right of the '@' sign, that information takes the following path:
- If it's a hostname or FQDN, this is attempted to be resolved to an IP address. If it resolves, that resulting IP address is passed through to the event.
- If it's a hostname or FQDN where the IP address cannot be resolved, then the hostname/FQDN is passed in as-is to the event and will create an event for that hostname/FQDN even if there is no match for a device in Zenoss.
- If it's already an IP address, it's passed through as-is to the event
- Once an IP address is passed in as a result of #1 or #3 above, zenmail checks that IP address to get a match for the parent device. This means that as long as the IP resolves to an interface on a device, whether it's the manage IP or not, Zenoss will resolve the address to the correct device in the Infrastructure and will associate the event with that device.
- 'Subject' field - This corresponds to what gets set as the 'Summary' in the resulting event
- 'Message' body - The text information in the body of the SMTP message, if it's been populated, becomes the 'Message' in the resulting event.
Testing:
There are two small sample test scripts linked to this article, one in Perl and the other in Python, that can be used for simple tests against the zenmail daemon to observe behavior and verify configuration. These can be run locally on the Zenoss server, or remotely from another system providing it has a routable path to the Zenoss server and has Perl and/or Python installed. The Perl version requires Net-SMTP. Both are commented heavier than necessary for ease of use.
Does it work for 5.x? Can you update this KB to work with 5.x?
There is a KB for version 5.x: https://support.zenoss.com/hc/en-us/articles/207439436-how-to-configure-ZenMail-in-Zenoss-Resource-Manager-5-x