[pmg-devel] [PATCH pmg-api/docs v4] fix #4211: convert quarantine link mail to template

[pmg-devel] [PATCH pmg-api/docs v4] fix #4211: convert quarantine link mail to template

[Stoiko Ivanov]

This series is a continuation of Christoph's excellent work from:
https://lore.proxmox.com/pmg-devel/20241008111753.831405-1-c.heiss@proxmox.com/T/#t

basically I wondered if/how it'd be easily possible to send only text/plain
reports or let the admin's add those additionally, w/o needing to
touch the code (by simply putting a fitting template in /etc/pmg/templates)

instead of sending half-thought through suggestions as reply I went ahead
and tried adapting the code.

changes from Christoph's v3:
* make it possible to send text/plain only mails (by
  `touch /etc/pmg/template/<html-template>.tt (and providing a fitting
   plaintext template)
* reworking finalize_report, and keeping its current signature (not a
  benefit in itself, but was a side-effect

I considered moving add a `.html.tt` suffix to the current templates (while
still checking the `.tt` ones to not ignore a modification on a user's system),
to keep the symmetry (`.html.tt`, `.plain.tt`), but decided to drop this
to create less churn.

@Christoph - hope the attribution of your work with a Co-developed-by
trailer[0] is ok (glad to change that if you prefer something else)?

[0] https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

pmg-api:
Christoph Heiss (1):
  fix #4211: convert quarantine link mail to template

Stoiko Ivanov (1):
  utils: allow specifying plain and/or html for finalize_report()

 src/Makefile                           |  2 +
 src/PMG/API2/Quarantine.pm             | 19 +++----
 src/PMG/Backup.pm                      |  2 +-
 src/PMG/CLI/pmgqm.pm                   |  6 +-
 src/PMG/CLI/pmgreport.pm               |  2 +-
 src/PMG/Utils.pm                       | 77 ++++++++++++++++++++++----
 src/templates/quarantine-link.plain.tt |  6 ++
 src/templates/quarantine-link.tt       | 13 +++++
 8 files changed, 98 insertions(+), 29 deletions(-)
 create mode 100644 src/templates/quarantine-link.plain.tt
 create mode 100644 src/templates/quarantine-link.tt

pmg-docs:
Christoph Heiss (1):
  pmgconfig: document support for html and plain-text email templates

 pmgconfig.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)

-- 
2.39.5



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

[pmg-devel] [PATCH pmg-api v4 1/2] utils: allow specifying plain and/or html for finalize_report()

[Stoiko Ivanov]

To support both plain-text and HTML emails when sending reports,
PMG::Utils::finalize_report() now checks if a template has a
plain-text equivalent - (`.plain.tt` instead of `.tt` as suffix).

if either template file is empty (or non-existant) the corresponding
part is simply left-out.

This should enable admins top optionally send plain-text only reports,
or multipart mails with both text/plain and text/html, while not
changing the current behavior

Co-developed-by: Christoph Heiss <c.heiss@proxmox.com>
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 src/PMG/Backup.pm        |  2 +-
 src/PMG/CLI/pmgqm.pm     |  6 ++--
 src/PMG/CLI/pmgreport.pm |  2 +-
 src/PMG/Utils.pm         | 77 +++++++++++++++++++++++++++++++++-------
 4 files changed, 70 insertions(+), 17 deletions(-)

diff --git a/src/PMG/Backup.pm b/src/PMG/Backup.pm
index ab7e628..c820d6b 100644
--- a/src/PMG/Backup.pm
+++ b/src/PMG/Backup.pm
@@ -418,7 +418,7 @@ sub send_backup_notification {
     my $tt = PMG::Config::get_template_toolkit();
 
     my $mailfrom = "Proxmox Mail Gateway <postmaster>";
-    PMG::Utils::finalize_report($tt, 'backup-notification.tt', $vars, $mailfrom, $email);
+    PMG::Utils::finalize_report($tt, 'backup-notification', $vars, $mailfrom, $email);
 
 }
 
diff --git a/src/PMG/CLI/pmgqm.pm b/src/PMG/CLI/pmgqm.pm
index 987ddc9..7016161 100755
--- a/src/PMG/CLI/pmgqm.pm
+++ b/src/PMG/CLI/pmgqm.pm
@@ -261,14 +261,14 @@ __PACKAGE__->register_method ({
 	my $domains = PVE::INotify::read_file('domains');
 	my $domainregex = PMG::Utils::domain_regex([keys %$domains]);
 
-	my $template = "spamreport-${reportstyle}.tt";
+	my $template = "spamreport-${reportstyle}";
 	my $found = 0;
 	foreach my $path (@$PMG::Config::tt_include_path) {
-	    if (-f "$path/$template") { $found = 1; last; }
+	    if (-f "$path/$template.tt") { $found = 1; last; }
 	}
 	if (!$found) {
 	    warn "unable to find template '$template' - using default\n";
-	    $template = "spamreport-verbose.tt";
+	    $template = "spamreport-verbose";
 	}
 
 	my $sth = $dbh->prepare(
diff --git a/src/PMG/CLI/pmgreport.pm b/src/PMG/CLI/pmgreport.pm
index 3403e44..99adfd2 100644
--- a/src/PMG/CLI/pmgreport.pm
+++ b/src/PMG/CLI/pmgreport.pm
@@ -359,7 +359,7 @@ __PACKAGE__->register_method ({
 	}
 
 	my $mailfrom = "Proxmox Mail Gateway <postmaster>";
-	PMG::Utils::finalize_report($tt, 'pmgreport.tt', $vars, $mailfrom, $email, $param->{debug});
+	PMG::Utils::finalize_report($tt, 'pmgreport', $vars, $mailfrom, $email, $param->{debug});
 
 	return undef;
     }});
diff --git a/src/PMG/Utils.pm b/src/PMG/Utils.pm
index 5d9ded4..9069f81 100644
--- a/src/PMG/Utils.pm
+++ b/src/PMG/Utils.pm
@@ -1248,32 +1248,85 @@ sub format_uptime {
     }
 }
 
+# Sends a report to the given receiver, building the body from templates.
+# if either html or plain template is empty that part is not added.
+# The subject of the mail is derived from the title tag of the HTML template, with a fallback to
+# the value after `subject:` on a line of its own in the plaintext template.
+#
+# The resulting mail is then reinjected with an empty envelope sender.
+#
+# Parameters:
+#   * `tt` - The template toolkit instance to use
+#   * `template_base` - base name of the template. suffixed with 'tt' yields the HTML template.
+#      suffixed with 'plain.tt' yields the plain text template
+#   * `data` - Template variables to pass to the template processor
+#   * `mailfrom` - Sender address
+#   * `receiver` - Recipient address
+#   * `debug` - whether to enable debug mode, resulting mail is only     printed, not reinjected
 sub finalize_report {
-    my ($tt, $template, $data, $mailfrom, $receiver, $debug) = @_;
+    my ($tt, $template_base, $data, $mailfrom, $receiver, $debug) = @_;
+
+    my $html_template;
+    my $html_path;
+    for my $path (@$PMG::Config::tt_include_path) {
+	if (-f "$path/$template_base.tt") {
+	    $html_template = "$template_base.tt";
+	    $html_path = "$path/$template_base.tt";
+	    last;
+	}
+    }
 
     my $html = '';
 
-    $tt->process($template, $data, \$html) ||
-	die $tt->error() . "\n";
-
+    if (defined($html_template) && -s $html_path) {
+	$tt->process($html_template, $data, \$html) ||
+	    die $tt->error() . "\n";
+    }
     my $title;
     if ($html =~ m|^\s*<title>(.*)</title>|m) {
 	$title = $1;
-    } else {
-	die "unable to extract template title\n";
     }
 
+    my $plain_template;
+    my $plain_path;
+    for my $path (@$PMG::Config::tt_include_path) {
+	if (-f "$path/$template_base.plain.tt") {
+	    $plain_template = "$template_base.plain.tt";
+	    $plain_path = "$path/$template_base.plain.tt";
+	    last;
+	}
+    }
+
+    my $plaintext = '';
+    if (defined($plain_template) && -s $plain_path) {
+	$tt->process($plain_template, $data, \$plaintext) ||
+	    die $tt->error() . "\n";
+    }
+
+    if ($plaintext =~ s/^subject: (.+)$//m) {
+	$title //= $1;
+    }
+
+    die "unable to extract template title\n" if !defined($title);
+
     my $top = MIME::Entity->build(
-	Type    => "multipart/related",
+	Type    => ($html && $plaintext) ? 'multipart/alternative' : 'multipart/related',
 	To      => $data->{pmail_raw},
 	From    => $mailfrom,
 	Subject => bencode_header(decode_entities($title)));
 
-    $top->attach(
-	Data     => $html,
-	Type     => "text/html",
-	Encoding => $debug ? 'binary' : 'quoted-printable');
-
+    if ($html) {
+	$top->attach(
+	    Data     => $html,
+	    Type     => "text/html",
+	    Encoding => $debug ? 'binary' : 'quoted-printable');
+    }
+    if ($plaintext) {
+	$top->attach(
+	    Data     => $plaintext,
+	    Type     => 'text/plain; charset=utf-8',
+	    Encoding => '8-bit');
+    }
     if ($debug) {
 	$top->print();
 	return;
-- 
2.39.5



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

[pmg-devel] [PATCH pmg-api v4 2/2] fix #4211: convert quarantine link mail to template

[Stoiko Ivanov]

From: Christoph Heiss <c.heiss@proxmox.com>

Fixes #4211 [0] by converting the currently hardcoded text for the
quarantine link mail to a proper template, enabling users to write their
own versions.

Pretty straight-forward change. The overall content/wording is kept
pretty much for the plain-text version, the HTML variant is adapted from
that as needed.

[0] https://bugzilla.proxmox.com/show_bug.cgi?id=4211

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
[S.I. adapt to changed arguments of finalize_report]
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 src/Makefile                           |  2 ++
 src/PMG/API2/Quarantine.pm             | 19 +++++++------------
 src/templates/quarantine-link.plain.tt |  6 ++++++
 src/templates/quarantine-link.tt       | 13 +++++++++++++
 4 files changed, 28 insertions(+), 12 deletions(-)
 create mode 100644 src/templates/quarantine-link.plain.tt
 create mode 100644 src/templates/quarantine-link.tt

diff --git a/src/Makefile b/src/Makefile
index 8e49a10..1232880 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -44,6 +44,8 @@ TEMPLATES =				\
 	postgresql.conf.in		\
 	pg_hba.conf.in			\
 	backup-notification.tt		\
+	quarantine-link.tt		\
+	quarantine-link.plain.tt	\
 
 TEMPLATES_FILES = $(addprefix templates/, ${TEMPLATES})
 
diff --git a/src/PMG/API2/Quarantine.pm b/src/PMG/API2/Quarantine.pm
index 9301da9..16dec57 100644
--- a/src/PMG/API2/Quarantine.pm
+++ b/src/PMG/API2/Quarantine.pm
@@ -1235,18 +1235,13 @@ my sub send_link_mail {
     my $esc_ticket = uri_escape($ticket);
     my $link = "$protocol_fqdn_port/quarantine?ticket=${esc_ticket}";
 
-    my $text = "Here is your Link for the Spam Quarantine on $fqdn:\n\n$link\n";
-
-    my $mail = MIME::Entity->build(
-	Type    => "text/plain",
-	To      => $receiver,
-	From    => $mailfrom,
-	Subject => "Proxmox Mail Gateway - Quarantine Link",
-	Data    => $text,
-    );
-
-    # we use an empty envelope sender (we don't want to receive NDRs)
-    PMG::Utils::reinject_local_mail ($mail, '', [$receiver], undef, $fqdn);
+    my $tt = PMG::Config::get_template_toolkit();
+    my $vars = {
+	fqdn => $fqdn,
+	link => $link,
+    };
+
+    PMG::Utils::finalize_report($tt, 'quarantine-link', $vars, $mailfrom, $receiver);
 }
 
 __PACKAGE__->register_method ({
diff --git a/src/templates/quarantine-link.plain.tt b/src/templates/quarantine-link.plain.tt
new file mode 100644
index 0000000..bb04e67
--- /dev/null
+++ b/src/templates/quarantine-link.plain.tt
@@ -0,0 +1,6 @@
+subject: Proxmox Mail Gateway - Quarantine Link
+Here is your link for the spam quarantine on [% fqdn %]:
+
+[% link %]
+
+Powered by http://www.proxmox.com
diff --git a/src/templates/quarantine-link.tt b/src/templates/quarantine-link.tt
new file mode 100644
index 0000000..d6fd17e
--- /dev/null
+++ b/src/templates/quarantine-link.tt
@@ -0,0 +1,13 @@
+[%- SET title = "Proxmox Mail Gateway - Quarantine Link" -%]
+<html>
+  <head>
+    <title>[% title %]</title>
+  </head>
+  <body>
+    <p>
+      Here is your link for the spam quarantine on <code>[% fqdn %]</code>: <a href='[% link | url %]'>Spam quarantine</a>
+    </p>
+
+    <p>Powered by <a target=_blank href='http://www.proxmox.com'>Proxmox</a>.</p>
+  </body>
+</html>
-- 
2.39.5



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

[pmg-devel] [PATCH pmg-docs v4 1/1] pmgconfig: document support for html and plain-text email templates

[Stoiko Ivanov]

From: Christoph Heiss <c.heiss@proxmox.com>

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
[S.I. adapt to changed semantics]
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 pmgconfig.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/pmgconfig.adoc b/pmgconfig.adoc
index a9377c5..e9833d4 100644
--- a/pmgconfig.adoc
+++ b/pmgconfig.adoc
@@ -155,6 +155,14 @@ engine, and the Apache {spamassassin} project. These services use
 separate configuration files, so we need to rewrite those files when the
 configuration is changed.
 
+{pmg} also features support for customizing the email-based reports and
+notifications it can send to administrators and users. These can be adjusted in
+the same way as configuration files. For some reports and notifications, both
+HTML and plain-text variants exist, which will be send together as multi-part
+mail. These can be recognized by being suffixed using `.html.tt` or `.plain.tt`,
+respectively, and should be modified together if available to present a
+consistent experience to users.
+
 We use a template-based approach to generate these files. The {tts} is
 a well known, fast and flexible template processing system. You can
 find the default templates in `/var/lib/pmg/templates/`. Please do not
-- 
2.39.5



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

Re: [pmg-devel] [PATCH pmg-api/docs v4] fix #4211: convert quarantine link mail to template

[Christoph Heiss]

Tested this series, by requesting a quarantine link and checking whether
the sent email is a valid multipart email and contains both a plain-text
and HTML attachment.

Didn't test the plain-text only part tho, since there currently is no
code-path that uses it (yet), FWIW.

Please consider the entire series:

Tested-by: Christoph Heiss <c.heiss@proxmox.com>
Reviewed-by: Christoph Heiss <c.heiss@proxmox.com>

On Mon, Oct 14, 2024 at 08:05:46PM GMT, Stoiko Ivanov wrote:
> This series is a continuation of Christoph's excellent work from:
> https://lore.proxmox.com/pmg-devel/20241008111753.831405-1-c.heiss@proxmox.com/T/#t
>
> [..]
>
> @Christoph - hope the attribution of your work with a Co-developed-by
> trailer[0] is ok (glad to change that if you prefer something else)?

Sure, totally fine by me as-is!


_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel