From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 34A1E1FF348 for ; Wed, 17 Apr 2024 16:35:25 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 61CCBAFE1; Wed, 17 Apr 2024 16:35:25 +0200 (CEST) From: Lukas Wagner To: pbs-devel@lists.proxmox.com Date: Wed, 17 Apr 2024 16:34:35 +0200 Message-Id: <20240417143514.346233-5-l.wagner@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240417143514.346233-1-l.wagner@proxmox.com> References: <20240417143514.346233-1-l.wagner@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL -0.004 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH proxmox v2 04/43] notify: endpoints: matcher: improve descriptions for API types X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox Backup Server development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pbs-devel-bounces@lists.proxmox.com Sender: "pbs-devel" 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 --- 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, /// 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, - /// 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, - /// `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, - /// Author of the mail + /// Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)' #[serde(skip_serializing_if = "Option::is_none")] pub author: Option, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, /// 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, #[serde(skip_serializing_if = "Option::is_none")] pub mode: Option, - /// 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, - /// 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, - /// 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, - /// `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, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, /// 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, } 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, - /// 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, - /// 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, - /// 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, - /// Invert match of the whole filter + /// Invert match of the whole filter. #[serde(skip_serializing_if = "Option::is_none")] pub invert_match: Option, - /// 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, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, - /// Disable this matcher + /// Disable this matcher. #[serde(skip_serializing_if = "Option::is_none")] pub disable: Option, -- 2.39.2 _______________________________________________ pbs-devel mailing list pbs-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel