smtp: Customize the SSL/TLS port support (#4757) by Gintoms · Pull Request #4818 · prometheus/alertmanager

Gintoms · 2025-12-17T10:03:30Z

Summary

The current email notification implementation has hardcoded logic that only enables direct TLS connections for port 465. This creates a limitation when using TLS on other ports, causing create SMTP client: EOF errors when the server expects TLS connections on non-465 ports.

Description

In notify/email/email.go:133, there's hardcoded logic that only uses tls.Dial() for port 465, while all other ports use plain TCP connections. This causes issues when SMTP servers require TLS connections on ports other than 465.

However, some SMTP servers may be configured to require TLS connections on non-standard ports but don't support STARTTLS, leading to EOF errors.

Spaceman1701

Thanks for opening this PR!

One general comment: Would you mind adding a summary to the PR? I'm aware that this is for #4757, but it helps discoverability if the PR has a descriptive summary.

Spaceman1701 · 2026-01-09T00:29:33Z

notify/email/email.go


 	// Global Config guarantees RequireTLS is not nil.
-	if *n.conf.RequireTLS {
+	if *n.conf.RequireTLS && !useImplicitTLS {


this subtle change in behavior - It seems like the logic on main will enter this branch regardless of the port (and thus regardless of whether we're using implicit tls). Was this change intentional?

So on one hand, it's silly to use STARTTLS on an existing secure connection... On the other hand, I'm a little worried about changing this behavior out from under people.

Do you know what the spec says about issuing STARTTLS on a secure connection? If this is defined as a no-op, I'm ok with the behavior change.

So on one hand, it's silly to use STARTTLS on an existing secure connection... On the other hand, I'm a little worried about changing this behavior out from under people.

Do you know what the spec says about issuing STARTTLS on a secure connection? If this is defined as a no-op, I'm ok with the behavior change.

Regarding the spec, RFC 3207 Section 4 explicitly forbids this behavior:
"A client MUST NOT attempt to start a TLS session if a TLS session is already active."

I think RFC 3207 is referring to sending STARTTLS more than once per session, not issuing STARTTLS on an implicit TLS connection.

That being said, RFC 8314 doesn't even seem to require a client which provides STARTTLS over cleartext also implement it on the implicit TLS port, so I'm inclined to agree that the current implementation is wrong.

Spaceman1701 · 2026-01-12T15:05:56Z

notify/email/email.go


 	// Global Config guarantees RequireTLS is not nil.
-	if *n.conf.RequireTLS {
+	if *n.conf.RequireTLS && !useImplicitTLS {


I think RFC 3207 is referring to sending STARTTLS more than once per session, not issuing STARTTLS on an implicit TLS connection.

That being said, RFC 8314 doesn't even seem to require a client which provides STARTTLS over cleartext also implement it on the implicit TLS port, so I'm inclined to agree that the current implementation is wrong.

Spaceman1701 · 2026-01-12T15:27:37Z

config/notifiers.go

+	// ImplicitTLS controls whether to use implicit TLS (direct TLS connection).
+	// true: force use of implicit TLS (direct TLS connection)
+	// nil (default): auto-detect based on port (465=implicit, other=explicit) for backward compatibility
+	ImplicitTLS      *bool                `yaml:"implicit_tls,omitempty" json:"implicit_tls,omitempty"`


Two small bikesheds: I think this should be called ForceImplicitTLS since implicit TLS is always enabled for port 465.

I also think this should be available as a global setting (like smtp_force_implicit_tls) since I think it's common to configure one smtp configuration for all email receivers.

alertmanager/config/config.go

Lines 984 to 994 in 3a2c66e

SMTPFrom string `yaml:"smtp_from,omitempty" json:"smtp_from,omitempty"`

SMTPHello string `yaml:"smtp_hello,omitempty" json:"smtp_hello,omitempty"`

SMTPSmarthost HostPort `yaml:"smtp_smarthost,omitempty" json:"smtp_smarthost,omitempty"`

SMTPAuthUsername string `yaml:"smtp_auth_username,omitempty" json:"smtp_auth_username,omitempty"`

SMTPAuthPassword Secret `yaml:"smtp_auth_password,omitempty" json:"smtp_auth_password,omitempty"`

SMTPAuthPasswordFile string `yaml:"smtp_auth_password_file,omitempty" json:"smtp_auth_password_file,omitempty"`

SMTPAuthSecret Secret `yaml:"smtp_auth_secret,omitempty" json:"smtp_auth_secret,omitempty"`

SMTPAuthSecretFile string `yaml:"smtp_auth_secret_file,omitempty" json:"smtp_auth_secret_file,omitempty"`

SMTPAuthIdentity string `yaml:"smtp_auth_identity,omitempty" json:"smtp_auth_identity,omitempty"`

SMTPRequireTLS bool `yaml:"smtp_require_tls" json:"smtp_require_tls,omitempty"`

SMTPTLSConfig *commoncfg.TLSConfig `yaml:"smtp_tls_config,omitempty" json:"smtp_tls_config,omitempty"`

Two small bikesheds: I think this should be called ForceImplicitTLS since implicit TLS is always enabled for port 465.

I also think this should be available as a global setting (like smtp_force_implicit_tls) since I think it's common to configure one smtp configuration for all email receivers.

alertmanager/config/config.go

Lines 984 to 994 in 3a2c66e

SMTPFrom string `yaml:"smtp_from,omitempty" json:"smtp_from,omitempty"`

SMTPHello string `yaml:"smtp_hello,omitempty" json:"smtp_hello,omitempty"`

SMTPSmarthost HostPort `yaml:"smtp_smarthost,omitempty" json:"smtp_smarthost,omitempty"`

SMTPAuthUsername string `yaml:"smtp_auth_username,omitempty" json:"smtp_auth_username,omitempty"`

SMTPAuthPassword Secret `yaml:"smtp_auth_password,omitempty" json:"smtp_auth_password,omitempty"`

SMTPAuthPasswordFile string `yaml:"smtp_auth_password_file,omitempty" json:"smtp_auth_password_file,omitempty"`

SMTPAuthSecret Secret `yaml:"smtp_auth_secret,omitempty" json:"smtp_auth_secret,omitempty"`

SMTPAuthSecretFile string `yaml:"smtp_auth_secret_file,omitempty" json:"smtp_auth_secret_file,omitempty"`

SMTPAuthIdentity string `yaml:"smtp_auth_identity,omitempty" json:"smtp_auth_identity,omitempty"`

SMTPRequireTLS bool `yaml:"smtp_require_tls" json:"smtp_require_tls,omitempty"`

SMTPTLSConfig *commoncfg.TLSConfig `yaml:"smtp_tls_config,omitempty" json:"smtp_tls_config,omitempty"`

Renamed to ForceImplicitTLS and added global config support as suggested.

Spaceman1701

thanks for making those changes, this lgtm

Signed-off-by: gintom <17498860+Gintoms@users.noreply.github.com>

* [ENHANCEMENT] docs(opsgenie): Fix description of `api_url` field. #4908 * [ENHANCEMENT] docs(slack): Document missing app configs. #4871 * [ENHANCEMENT] docs: Fix `max-silence-size-bytes`. #4805 * [ENHANCEMENT] docs: Update expr for `AlertmanagerClusterFailedToSendAlerts` to exclude value 0. #4872 * [ENHANCEMENT] docs: Use matchers for inhibit rules examples. #4131 * [ENHANCEMENT] docs: add notification integrations. #4901 * [ENHANCEMENT] docs: update `slack_config` attachments documentation links. #4802 * [ENHANCEMENT] docs: update description of filter query params in openapi doc. #4810 * [ENHANCEMENT] provider: Reduce lock contention. #4809 * [FEATURE] slack: Add support for top-level text field in slack notification. #4867 * [FEATURE] smtp: Add support for authsecret from file. #3087 * [FEATURE] smtp: Customize the ssl/tls port support (#4757). #4818 * [FEATURE] smtp: Enhance email notifier configuration validation. #4826 * [FEATURE] telegram: Add `chat_id_file` configuration parameter. #4909 * [FEATURE] telegram: Support global bot token. #4823 * [FEATURE] webhook: Support templating in url fields. #4798 * [FEATURE] wechat: Add config directive to pass api secret via file. #4734 * [FEATURE] provider: Implement per alert limits. #4819 * [BUGFIX] Allow empty `group_by` to override parent route. #4825 * [BUGFIX] Set `spellcheck=false` attribute on silence filter input. #4811 * [BUGFIX] jira: Fix for handling api v3 with ADF. #4756 * [BUGFIX] jira: Prevent hostname corruption in cloud api url replacement. #4892 --------- Signed-off-by: Solomon Jacobs <solomonjacobs@protonmail.com> Signed-off-by: Ben Kochie <superq@gmail.com> Co-authored-by: Ben Kochie <superq@gmail.com>

nutmos · 2026-02-21T10:51:05Z

Hi, just wondering which field name should I use? I saw the doc uses implicit_tls while I saw from this commit, it should be force_implicit_tls.

Spaceman1701 · 2026-02-21T15:29:22Z

Hi, just wondering which field name should I use? I saw the doc uses implicit_tls while I saw from this commit, it should be force_implicit_tls.

Hi! It looks like the docs are wrong - the field is force_implicit_tls. I'll open a PR to fix the docs later today. Sorry about that!

Gintoms mentioned this pull request Dec 19, 2025

If I customize the SSL/TLS port, how should Alertmanager support? #4757

Closed

TheMeier added the component/notify label Dec 20, 2025

Spaceman1701 self-assigned this Dec 23, 2025

Spaceman1701 reviewed Jan 9, 2026

View reviewed changes

Gintoms force-pushed the fix/tls-port branch from 81f1d8f to c65bf36 Compare January 12, 2026 05:34

Spaceman1701 reviewed Jan 12, 2026

View reviewed changes

Gintoms force-pushed the fix/tls-port branch from c65bf36 to e01a13a Compare January 28, 2026 03:10

Spaceman1701 approved these changes Jan 28, 2026

View reviewed changes

Spaceman1701 requested a review from ultrotter January 28, 2026 17:20

ultrotter approved these changes Jan 28, 2026

View reviewed changes

Customize the SSL/TLS port support (prometheus#4757)

d43f024

Signed-off-by: gintom <17498860+Gintoms@users.noreply.github.com>

Gintoms force-pushed the fix/tls-port branch from e01a13a to d43f024 Compare January 29, 2026 01:54

SuperQ changed the title ~~Customize the SSL/TLS port support (#4757)~~ smtp: Customize the SSL/TLS port support (#4757) Jan 30, 2026

SuperQ merged commit bc26ebb into prometheus:main Jan 30, 2026
7 checks passed

SoloJacobs mentioned this pull request Jan 30, 2026

Release v0.31.0 #4916

Merged

guoard mentioned this pull request Feb 8, 2026

Fix email tls configuration example in docs #4976

Merged

nutmos mentioned this pull request Feb 21, 2026

Fix: rename implicit_tls to force_implicit_tls for SMTP in Alertmanager secret config prometheus-operator/prometheus-operator#8404

Merged

5 tasks

Spaceman1701 mentioned this pull request Feb 21, 2026

fix: force_implicit_tls config field name in docs #5030

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

smtp: Customize the SSL/TLS port support (#4757)#4818

smtp: Customize the SSL/TLS port support (#4757)#4818
SuperQ merged 1 commit intoprometheus:mainfrom
Gintoms:fix/tls-port

Gintoms commented Dec 17, 2025 •

edited

Loading

Uh oh!

Spaceman1701 left a comment

Uh oh!

Spaceman1701 Jan 9, 2026

Uh oh!

Gintoms Jan 9, 2026

Uh oh!

Spaceman1701 Jan 9, 2026

Uh oh!

Gintoms Jan 12, 2026

Uh oh!

Spaceman1701 Jan 12, 2026

Uh oh!

Spaceman1701 Jan 12, 2026

Uh oh!

Spaceman1701 Jan 12, 2026

Uh oh!

Gintoms Jan 28, 2026

Uh oh!

Spaceman1701 left a comment

Uh oh!

Uh oh!

nutmos commented Feb 21, 2026

Uh oh!

Spaceman1701 commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

	SMTPFrom string `yaml:"smtp_from,omitempty" json:"smtp_from,omitempty"`
	SMTPHello string `yaml:"smtp_hello,omitempty" json:"smtp_hello,omitempty"`
	SMTPSmarthost HostPort `yaml:"smtp_smarthost,omitempty" json:"smtp_smarthost,omitempty"`
	SMTPAuthUsername string `yaml:"smtp_auth_username,omitempty" json:"smtp_auth_username,omitempty"`
	SMTPAuthPassword Secret `yaml:"smtp_auth_password,omitempty" json:"smtp_auth_password,omitempty"`
	SMTPAuthPasswordFile string `yaml:"smtp_auth_password_file,omitempty" json:"smtp_auth_password_file,omitempty"`
	SMTPAuthSecret Secret `yaml:"smtp_auth_secret,omitempty" json:"smtp_auth_secret,omitempty"`
	SMTPAuthSecretFile string `yaml:"smtp_auth_secret_file,omitempty" json:"smtp_auth_secret_file,omitempty"`
	SMTPAuthIdentity string `yaml:"smtp_auth_identity,omitempty" json:"smtp_auth_identity,omitempty"`
	SMTPRequireTLS bool `yaml:"smtp_require_tls" json:"smtp_require_tls,omitempty"`
	SMTPTLSConfig *commoncfg.TLSConfig `yaml:"smtp_tls_config,omitempty" json:"smtp_tls_config,omitempty"`

Conversation

Gintoms commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Description

Uh oh!

Spaceman1701 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Spaceman1701 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nutmos commented Feb 21, 2026

Uh oh!

Spaceman1701 commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Gintoms commented Dec 17, 2025 •

edited

Loading