See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-679

From Zabbix.org
Jump to: navigation, search

Support for SMTP authentication

ZBXNEXT-679

Status: v1.1

Owner: Aleksandrs

Summary

Currently, Zabbix server can only send email alerts by connecting to a hardcoded port 25 of the specified SMTP server and sending an email without encryption or authentication. This task is meant to add encryption and authentication support by using the cURL library.

Frontend changes

In "Email" media type configuration in "Administration" -> "Media types", the "Port" field should be added to the right of "SMTP server" field:

SMTP server          _______________________  Port _____

The following fields should be added below "SMTP email" field:

Connection security  [None|STARTTLS|SSL/TLS]
SSL verify peer      [ ]
SSL verify host      [ ]
Authentication       [None|Normal password]
User                 _______________________
Password             _______________________

If "Connection security" is set to "None", then "SSL verify peer" and "SSL verify host" checkboxes should not be visible.

If "Authentication" is set to "None", then "User" and "Password" fields should not be visible.

"Connection security" and "Authentication" should default to "None".

"Port" should default to "25" and it is a numeric box. It cannot be empty, contain letters and be negative.

"Port", "User", and "Password" fields should be validated.

Server-side changes

If "Connection security" and "Authentication" are both set to "None", then we send emails as before, without requiring the server to be compiled with the cURL library. However, support for "Port" should be added.

Otherwise, if at least one of "Connection security" and "Authentication" are not "None", we should use the cURL library. Documentation for cURL gives an example on how to send emails using the library, which we can use as the basis for implementation. The rest of this section describes our working with cURL.

The setting of "Connection security" has the following effects:

  • if set to "None", we should use "smtp://" scheme when constructing the URL and CURLOPT_USE_SSL should not be used;
  • if set to "STARTTLS", we should use "smtp://" scheme and CURLOPT_USE_SSL should be set to CURLUSESSL_ALL to require SSL;
  • if set to "SSL/TLS", we should use "smtps://" scheme and the use of CURLOPT_USE_SSL is optional, although this should be verified.

The setting of "Authentication" has the following effects:

Additional research is needed whether we wish to support SASL mechanisms other than PLAIN. We might wish to add other mechanisms on an on-demand basis. Meanwhile, officially registered SASL mechanisms are described on the IANA page. Note that mechanisms such as DIGEST-MD5, which appear in SMTP authentication examples, have OBSOLETE status.

String from "SMTP helo" field in the frontend should be passed to cURL in CURLOPT_URL, see SMTP section for syntax.

Similarly to ZBXNEXT-282, "SSL verify peer" and "SSL verify host" should use CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST, and the value of "SSLCALocation" server configuration directive should be put into CURLOPT_CAPATH for certificate validation.

If SMTP server does not accept Zabbix connection due to unsupported security level or SMTP authentication fails, then email sending fails, too, and we do not automatically retry with a different configuration.

The following line with YES/NO should be added to the list of enabled features before "Jabber notifications" for Zabbix server:

SMTP authentication:       YES

Portability

Option CURLOPT_LOGIN_OPTIONS was added in cURL 7.34.0. According to ZBX-8389, we currently support versions of cURL before 7.16.4 in the rest of server code. Therefore, when doing the new email implementation, we should use conditionals similar to the following:

#if defined(HAVE_LIBCURL) && 0x072200 <= LIBCURL_VERSION_NUM	/* version 7.34.0 */

...

#endif

Other options that we need were added earlier:

Translation strings

  • Connection security
  • STARTTLS
  • SSL/TLS
  • Normal password

Database changes

New fields for table "media_type":

FIELD     |smtp_port           |t_integer     |'25'|NOT NULL     |0
FIELD     |smtp_security       |t_integer     |'0' |NOT NULL     |0     # 0 - "None", 1 - "STARTTLS", 2 - "SSL/TLS"
FIELD     |smtp_verify_peer    |t_integer     |'0' |NOT NULL     |0     # 0 - no, 1 - yes
FIELD     |smtp_verify_host    |t_integer     |'0' |NOT NULL     |0     # 0 - no, 1 - yes
FIELD     |smtp_authentication |t_integer     |'0' |NOT NULL     |0     # 0 - "None", 1 - "Normal password"

"User" and "Password" fields in the frontend should use existing "username" and "passwd" fields in the database.

API changes

...

Documentation

To be decided

  • According to #1367 SMTP authentification option, it is possible to use CURLOPT_USERPWD in order to provide the opportunity to select a login method. However, this method only works with cURL versions >= 7.31.0 and < 7.34.0 (this is further confirmed by cURL 7.34.0 release notes). It should be decided whether we wish to support these older versions.
  • When editing a "Jabber" media type, the "Password" field is initially a "Change password" button. When editing an "Ez Texting" media type, it is initially a password field. It should be decided how we wish the password field to look for "Email" media type and unify with the rest of media types.
  • Should "STARTTLS" and "SSL/TLS" strings be translatable?

ChangeLog

v1.1

  • added "smtp_" prefix to database fields
  • "media_type.smtp_port" should default to "25"
  • notes on "Port", "User", "Password" field validation
  • position of "SMTP authentication" in server feature list
  • what happens if SMTP server does not accept our connection