From: Lukas Wagner <l.wagner@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [pbs-devel] [PATCH proxmox v2 04/43] notify: endpoints: matcher: improve descriptions for API types
Date: Wed, 17 Apr 2024 16:34:35 +0200 [thread overview]
Message-ID: <20240417143514.346233-5-l.wagner@proxmox.com> (raw)
In-Reply-To: <20240417143514.346233-1-l.wagner@proxmox.com>
proxmox-schema will automatically append text (e.g. 'Can be specified
more than once'), so we should end every comment with a '.'.
Also copy over some text from PVE docs, since these doc comments will
now be visible in the PBS documentation.
Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
proxmox-notify/src/endpoints/gotify.rs | 6 ++---
proxmox-notify/src/endpoints/sendmail.rs | 15 ++++++++-----
proxmox-notify/src/endpoints/smtp.rs | 28 +++++++++++++++---------
proxmox-notify/src/matcher.rs | 18 +++++++--------
4 files changed, 40 insertions(+), 27 deletions(-)
diff --git a/proxmox-notify/src/endpoints/gotify.rs b/proxmox-notify/src/endpoints/gotify.rs
index 70675c8..dc8326a 100644
--- a/proxmox-notify/src/endpoints/gotify.rs
+++ b/proxmox-notify/src/endpoints/gotify.rs
@@ -40,12 +40,12 @@ pub(crate) const GOTIFY_TYPENAME: &str = "gotify";
#[serde(rename_all = "kebab-case")]
/// Config for Gotify notification endpoints
pub struct GotifyConfig {
- /// Name of the endpoint
+ /// Name of the endpoint.
#[updater(skip)]
pub name: String,
- /// Gotify Server URL
+ /// Gotify Server URL.
pub server: String,
- /// Comment
+ /// Comment.
#[serde(skip_serializing_if = "Option::is_none")]
pub comment: Option<String>,
/// Deprecated.
diff --git a/proxmox-notify/src/endpoints/sendmail.rs b/proxmox-notify/src/endpoints/sendmail.rs
index 47901ef..da0c0cc 100644
--- a/proxmox-notify/src/endpoints/sendmail.rs
+++ b/proxmox-notify/src/endpoints/sendmail.rs
@@ -43,21 +43,26 @@ pub struct SendmailConfig {
/// Name of the endpoint
#[updater(skip)]
pub name: String,
- /// Mail recipients
+ /// Mail address to send a mail to.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub mailto: Vec<String>,
- /// Mail recipients
+ /// Users to send a mail to. The email address of the user
+ /// will be looked up in users.cfg.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub mailto_user: Vec<String>,
- /// `From` address for the mail
+ /// `From` address for sent E-Mails.
+ /// If the parameter is not set, the plugin will fall back to the
+ /// email-from setting from node.cfg (PBS).
+ /// If that is also not set, the plugin will default to root@$hostname,
+ /// where $hostname is the hostname of the node.
#[serde(skip_serializing_if = "Option::is_none")]
pub from_address: Option<String>,
- /// Author of the mail
+ /// Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)'
#[serde(skip_serializing_if = "Option::is_none")]
pub author: Option<String>,
- /// Comment
+ /// Comment.
#[serde(skip_serializing_if = "Option::is_none")]
pub comment: Option<String>,
/// Deprecated.
diff --git a/proxmox-notify/src/endpoints/smtp.rs b/proxmox-notify/src/endpoints/smtp.rs
index f04583a..27afeba 100644
--- a/proxmox-notify/src/endpoints/smtp.rs
+++ b/proxmox-notify/src/endpoints/smtp.rs
@@ -66,33 +66,41 @@ pub enum SmtpMode {
#[serde(rename_all = "kebab-case")]
/// Config for Sendmail notification endpoints
pub struct SmtpConfig {
- /// Name of the endpoint
+ /// Name of the endpoint.
#[updater(skip)]
pub name: String,
- /// Host name or IP of the SMTP relay
+ /// Host name or IP of the SMTP relay.
pub server: String,
- /// Port to use when connecting to the SMTP relay
+ /// The port to connect to.
+ /// If not set, the used port defaults to 25 (insecure), 465 (tls)
+ /// or 587 (starttls), depending on the value of mode
#[serde(skip_serializing_if = "Option::is_none")]
pub port: Option<u16>,
#[serde(skip_serializing_if = "Option::is_none")]
pub mode: Option<SmtpMode>,
- /// Username for authentication
+ /// Username to use during authentication.
+ /// If no username is set, no authentication will be performed.
+ /// The PLAIN and LOGIN authentication methods are supported
#[serde(skip_serializing_if = "Option::is_none")]
pub username: Option<String>,
- /// Mail recipients
+ /// Mail address to send a mail to.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub mailto: Vec<String>,
- /// Mail recipients
+ /// Users to send a mail to. The email address of the user
+ /// will be looked up in users.cfg.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub mailto_user: Vec<String>,
- /// `From` address for the mail
+ /// `From` address for the mail.
+ /// SMTP relays might require that this address is owned by the user
+ /// in order to avoid spoofing. The `From` header in the email will be
+ /// set to `$author <$from-address>`.
pub from_address: String,
- /// Author of the mail
+ /// Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)'
#[serde(skip_serializing_if = "Option::is_none")]
pub author: Option<String>,
- /// Comment
+ /// Comment.
#[serde(skip_serializing_if = "Option::is_none")]
pub comment: Option<String>,
/// Disable this target.
@@ -136,7 +144,7 @@ pub struct SmtpPrivateConfig {
/// Name of the endpoint
#[updater(skip)]
pub name: String,
- /// Authentication token
+ /// The password to use during authentication.
#[serde(skip_serializing_if = "Option::is_none")]
pub password: Option<String>,
}
diff --git a/proxmox-notify/src/matcher.rs b/proxmox-notify/src/matcher.rs
index 2d30378..986deee 100644
--- a/proxmox-notify/src/matcher.rs
+++ b/proxmox-notify/src/matcher.rs
@@ -108,42 +108,42 @@ pub const MATCH_FIELD_ENTRY_SCHEMA: Schema = StringSchema::new("Match metadata f
#[serde(rename_all = "kebab-case")]
/// Config for Sendmail notification endpoints
pub struct MatcherConfig {
- /// Name of the matcher
+ /// Name of the matcher.
#[updater(skip)]
pub name: String,
- /// List of matched metadata fields
+ /// List of matched metadata fields.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub match_field: Vec<FieldMatcher>,
- /// List of matched severity levels
+ /// List of matched severity levels.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub match_severity: Vec<SeverityMatcher>,
- /// List of matched severity levels
+ /// List of matched severity levels.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub match_calendar: Vec<CalendarMatcher>,
- /// Decide if 'all' or 'any' match statements must match
+ /// Decide if 'all' or 'any' match statements must match.
#[serde(skip_serializing_if = "Option::is_none")]
pub mode: Option<MatchModeOperator>,
- /// Invert match of the whole filter
+ /// Invert match of the whole filter.
#[serde(skip_serializing_if = "Option::is_none")]
pub invert_match: Option<bool>,
- /// Targets to notify
+ /// Targets to notify.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[updater(serde(skip_serializing_if = "Option::is_none"))]
pub target: Vec<String>,
- /// Comment
+ /// Comment.
#[serde(skip_serializing_if = "Option::is_none")]
pub comment: Option<String>,
- /// Disable this matcher
+ /// Disable this matcher.
#[serde(skip_serializing_if = "Option::is_none")]
pub disable: Option<bool>,
--
2.39.2
_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
next prev parent reply other threads:[~2024-04-17 14:35 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-17 14:34 [pbs-devel] [PATCH many v2 00/43] integrate notification system Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox v2 01/43] notify: expose `config` module Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox v2 02/43] notify: use std::sync::OnceCell instead of lazy_static! Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox v2 03/43] notify: pbs-context: exclude successful prunes in default matcher Lukas Wagner
2024-04-17 14:34 ` Lukas Wagner [this message]
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox v2 05/43] notify: sys: move 'email' module from proxmox_sys to proxmox_notify Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox v2 06/43] notify: add getter for notification timestamp Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH widget-toolkit v2 07/43] sendmail: smtp: allow to overide default mail author Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 08/43] pbs-config: add module for loading notification config Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 09/43] server: rename email_notifications module to notifications Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 10/43] notifications: allow sending notifications via proxmox_notify Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 11/43] buildsys: install templates for test notifications Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 12/43] pbs-config: acl: add /system/notifications as known ACL path Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 13/43] api: add endpoints for querying/testing notification targets Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 14/43] api: add endpoints for notification matchers Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 15/43] api: add endpoints for sendmail targets Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 16/43] api: add endpoints for smtp targets Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 17/43] api: add endpoints for gotify targets Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 18/43] api: add endpoints for querying known notification values/fields Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 19/43] api-types: api: datatore: add notification-mode parameter Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 20/43] api-types: api: tape: " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 21/43] server: notifications: send GC notifications via notification system Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 22/43] server: notifications: send prune " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 23/43] server: notifications: send verify " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 24/43] server: notifications: send sync " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 25/43] server: notifications: send update " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 26/43] server: notifications: send acme " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 27/43] server: notifications: send tape " Lukas Wagner
2024-04-17 14:34 ` [pbs-devel] [PATCH proxmox-backup v2 28/43] ui: add notification config panel Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 29/43] ui: tape backup job: add selector for notification-mode Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 30/43] ui: tape backup: add selector for 'notification-mode' Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 31/43] ui: tape restore: add 'notification-mode' parameter Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 32/43] ui: datastore options: " Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 33/43] ui: utils: add overrides for known notification metadata fields/values Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 34/43] ui: datastore edit: make new stores use notification system by default Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 35/43] ui: permissions paths: add /system/notifications to combobox Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 36/43] proxmox-backup-manager: add CLI for notification targets Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 37/43] proxmox-backup-manager: add CLI for notification matchers Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 38/43] proxmox-backup-manager: add CLI for gotify endpoints Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 39/43] proxmox-backup-manager: add CLI for sendmail endpoints Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 40/43] proxmox-backup-manager: add CLI for SMTP endpoints Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 41/43] docgen: generate synopsis for notifications{-priv, }.cfg Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 42/43] docs: add documentation for notification system Lukas Wagner
2024-04-17 14:35 ` [pbs-devel] [PATCH proxmox-backup v2 43/43] ui: util: override default mail author for sendmail/smtp targets 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=20240417143514.346233-5-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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox