all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Lukas Wagner <l.wagner@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [PATCH proxmox-backup] docs: notifications: expand notification queue documentation
Date: Fri, 20 Nov 2026 09:40:40 +0100	[thread overview]
Message-ID: <20261120084042.94455-1-l.wagner@proxmox.com> (raw)

Move the description of queued delivery out of the overview into its
own section and extend it, mirroring the Proxmox VE documentation.

Point out where to find the logs of the proxmox-backup service in the
GUI, how interrupted deliveries are retried and that this can lead to
duplicate notifications for some targets, and describe the queue
directory, including the naming scheme of queued files and what files
with a '.broken' suffix mean.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 docs/notifications.rst | 53 ++++++++++++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/docs/notifications.rst b/docs/notifications.rst
index 1355e2f17..621e3e872 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -17,16 +17,6 @@ Overview
   is routed to by a matcher. There are multiple types of target, mail-based
   (Sendmail and SMTP) and Gotify.
 
-Notification events are not sent by the process that emits them. They are put
-into a queue and sent by the ``proxmox-backup`` service within a few seconds.
-Errors while sending, for example an unreachable mail server, are therefore
-logged to the system journal of that service, see
-``journalctl -u proxmox-backup``, not to the task log of the job that emitted
-the event. Test notifications sent from the GUI are the exception, they are
-sent directly, so that the result can be shown. If the service is interrupted
-while sending a notification, it sends the notification again after it has been
-restarted.
-
 Global notification settings can be configured in the GUI under *Configuration →
 Notifications*. The configuration is stored in :ref:`notifications.cfg` and
 :ref:`notifications_priv.cfg` - the latter contains sensitive configuration
@@ -447,6 +437,49 @@ Metadata field       Description
 .. NOTE:: The daily task checking for any available system updates only sends
    notifications if the node has an active subscription.
 
+.. _notification_queue:
+
+Notification Queue
+------------------
+
+Notification events are not sent directly by the process that emits them.
+Instead, they are put into a local queue and sent by the ``proxmox-backup``
+service within a few seconds. Errors while sending, for example an unreachable
+mail server, are therefore logged to the system journal of that service, not to
+the task log of the job that emitted the event. Test notifications sent from the
+GUI are the exception: these are sent directly, so that the result can be shown.
+
+Logs for the ``proxmox-backup`` service can be viewed in the GUI under
+*Administration → Services*, by selecting the ``proxmox-backup`` service and
+clicking the *Service System Log* button. Alternatively, run
+``journalctl -u proxmox-backup``.
+
+If the service is shut down gracefully while sending a notification (e.g. due to
+a ``systemctl stop proxmox-backup``), the service attempts to finish sending
+before shutting down. If the service is stopped irregularly, e.g. due to a crash
+or being killed, it sends the notification again after it has been restarted.
+There can be up to 2 retries after the initial attempt, after which the
+notification is dropped. Targets that have already been notified during a prior
+attempt may be notified again. The retries only cover interruptions of the
+service. Failed deliveries to individual targets, for example due to an
+unreachable email server, are not retried.
+
+The local notification queue is located at
+``/var/lib/proxmox-backup/notifications/queue``, with each queued notification
+being a file in this directory. Notification files follow the naming scheme
+``notification-<uuid>`` with an optional appended attempt counter, for instance
+``notification-46516f7e-7eb7-43e7-b776-6048f144a6fe`` for a freshly queued
+notification or ``notification-46516f7e-7eb7-43e7-b776-6048f144a6fe.attempt-1``
+for a notification that is either currently being handled or was interrupted
+during the first attempt.
+
+Generally, this directory should be empty if all queued notifications have been
+sent. Notification files with a ``.broken`` suffix indicate that the file could
+not be successfully handled by the ``proxmox-backup`` service, either due to
+invalid contents or other unexpected properties. The service appends the suffix
+to allow further investigation by the administrator. It is safe to remove
+``.broken`` files at any moment.
+
 System Mail Forwarding
 ----------------------
 Certain local system daemons, such as ``smartd``, send notification emails to
-- 
2.47.3





             reply	other threads:[~2026-11-20  8:40 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-20  8:40 Lukas Wagner [this message]
2026-11-20  8:50 ` [PATCH proxmox-backup] docs: notifications: expand notification queue documentation Lukas Wagner

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261120084042.94455-1-l.wagner@proxmox.com \
    --to=l.wagner@proxmox.com \
    --cc=pbs-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal