From: Nick Porter Date: Fri, 7 Mar 2025 14:41:38 +0000 (+0000) Subject: Tidy comments for sample rlm_smtp config X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e4d03a30f3aaa67c8f42b69d4cfb9a12ed8e5090;p=thirdparty%2Ffreeradius-server.git Tidy comments for sample rlm_smtp config --- diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/smtp.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/smtp.adoc index c0ddc98ad5..c664fe0c94 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/smtp.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/smtp.adoc @@ -158,91 +158,115 @@ the underlying mail protocols. The URI should be in the form of: `SCHEME://IP:PORT/` -`SCHEME` can be one of the SMTP protocols supported by Curl. -i.e. smtp, smtps. -If no `SCHEME` is given, it defaults to `smtp`. + * `SCHEME` can be one of the SMTP protocols supported by Curl. + i.e. smtp, smtps. + If no `SCHEME` is given, it defaults to `smtp`. -`IP` is the IP address of the server. It can be an IPv4 address, -IPv6 address, hostname, etc. + * `IP` is the IP address of the server. It can be an IPv4 address, + IPv6 address, hostname, etc. -`PORT` is optional, and will normally be chosen to be correct -for the given `SCHEME`. + * `PORT` is optional, and will normally be chosen to be correct + for the given `SCHEME`. -For more information, see the CURL documentation at +For more information, see the CURL documentation at: https://ec.haxx.se/cmdline/cmdline-urls -timeout:: How long the module will wait before giving up on the response +timeout:: How long the module will wait, before giving up on the response from the SMTP server. -username_attribute:: Which attribute in the request should be used as -the user's username when performing SMTP authentication. +authenticate: Configuration for verifying a users name and clear-text password +against an SMTP server. +This is not generally recommended, but is supported for cases where an LDAP server +is not available, and only an SMTP server is available. -password_attribute:: Which attribute in the request should be used as -the user's password when performing SMTP authentication. +username:: The users name when performing SMTP authentication. -username:: User name to use when sending emails. Can be a fixed -string or an attribute. Leave unset if authentication is not -required to send emails. +password_attribute:: The users password when performing SMTP authentication -password:: Password to use in conjunction with the above user name -for SMTP authentication. +In most cases, the SMTP module will be used to send email. -template_directory:: The source directory where all file attachments are pulled from -All file attachments should be their relative path from this location, without a leading / +username:: The name or login identifier to use when sending email. +If authentication is not required, it can be commented out/ -Attachments:: attachments with their relative path from template_directory -There can be no leading / or .. +password:: Password to use when sending email. -envelope_address:: This is the address used to send the mail, -Sent to the receiving server as MAIL FROM: -sender_address will be defaulted to if this is not set +template_directory:: Directory where email templates are stored. +All file attachments should be given as a relative path +from this location. i.e. without a leading '/'. -sender_address:: This are the addresses displayed in the FROM: element of the header -This can be different than the provided envelope_address, -If envelope_address is set, this can be formatted however you want it to appear to the receiver -If envelope_address is not set, the first element in sender_address will be used as the envelope address + + +Attachments:: File names to attach to the templates. + +The filenames are relative to `template_directory` + + + +envelope_address:: Set the `MAIL FROM:` + +If this is not set, `MAIL FROM` will be set from `sender_address`. + + + +sender_address:: Set the body `FROM` address. + +This can be different than the provided envelope_address. + +If envelope_address is set, this can be formatted however +you want it to appear to the receiver. + +If envelope_address is not set, the first element in +sender_address will be used as the envelope address. recipients:: Email addresses to be set as recipients for the email -If recipients is set bcc, cc, and to will not be automatically added to the email -And so they must be included here. +If recipients is set, then `bcc`, `cc`, and `to` will not +be automatically added to the email. Only the list of +`recipients` will be used. -to:: Email addresses to be set in the TO: header -These addresses will be added as envelope recipients only if recipients is not set +to:: Set the body `TO` header. -cc:: Email addresses to be set in the CC: header -These addresses will be added as envelope recipients only if recipients is not set +If `recepients` is not set, then messages will be sent to the `TO` address. -bcc:: Comma separated list of emails. -the local part may contain commas, the domain may not (https://tools.ietf.org/html/rfc2821[RFC 2821]) -Therefore, first comma after the @ represents a new address -not listed in the header of the email -if recipients is not set, these emails will be added to the envelope recipients +cc:: Set the body `CC` header. + +If `recepients` is not set, then messages will also be sent to the `CC` addresses. + + + +bcc:: Set the `BCC` recipients. + +The local part may contain commas, the domain may not (https://tools.ietf.org/html/rfc2821[RFC 2821]) + +Therefore, the first comma after the @ represents a new +address, and is not listed in the header of the email. + +If `recepients` is not set, then messages will also be sent to the `CCC` addresses. @@ -261,10 +285,18 @@ Default is `yes` -header:: This is where any other headers can be added to the email -FROM, TO, and CC, should not be added here if their respective elements were set in the config -If no DATE header is provided, one will be added showing time that the request was received(recommended) -Non-standard mail headers may be set. Adhere to your MTA's documentation +header:: Additional headers to add to the messages. + +Any `FROM`, `TO`, and `CC` should not be added here. They are set in the configuration items above. + +If no `DATE` header is provided, one will be added which +shows the time that the request was sent. + +Non-standard mail headers may be set. Adhere to your MTA's +documentation + + +Headers are added with the given names and values, in the order listed here. @@ -329,7 +361,7 @@ smtp { } # username = "user" # password = "secret" - template_directory = raddb/mods_config/smtp + template_directory = ${confdir}/mods_config/smtp/ attachments = SMTP-Attachments[*] envelope_address = "postmaster@localhost" sender_address = SMTP-Sender-Address[*] diff --git a/raddb/mods-available/smtp b/raddb/mods-available/smtp index 60c53761bb..e47ef9e5bc 100644 --- a/raddb/mods-available/smtp +++ b/raddb/mods-available/smtp @@ -174,25 +174,25 @@ smtp { # # `SCHEME://IP:PORT/` # - - # `SCHEME` can be one of the SMTP protocols supported by Curl. - # i.e. smtp, smtps. - # If no `SCHEME` is given, it defaults to `smtp`. # - # `IP` is the IP address of the server. It can be an IPv4 address, - # IPv6 address, hostname, etc. + # * `SCHEME` can be one of the SMTP protocols supported by Curl. + # i.e. smtp, smtps. + # If no `SCHEME` is given, it defaults to `smtp`. + # + # * `IP` is the IP address of the server. It can be an IPv4 address, + # IPv6 address, hostname, etc. # - # `PORT` is optional, and will normally be chosen to be correct - # for the given `SCHEME`. + # * `PORT` is optional, and will normally be chosen to be correct + # for the given `SCHEME`. # - # For more information, see the CURL documentation at + # For more information, see the CURL documentation at: # # https://ec.haxx.se/cmdline/cmdline-urls # uri = "smtp://192.0.20.1/" # - # timeout:: How long the module will wait before giving up on the response + # timeout:: How long the module will wait, before giving up on the response # from the SMTP server. # timeout = 5s @@ -221,34 +221,36 @@ smtp { # # - # username:: User name to use when sending emails. Can be a fixed - # string or an attribute. Leave unset if authentication is not - # required to send emails. + # username:: The name or login identifier to use when sending email. + # + # If authentication is not required, it can be commented out/ # # username = "user" # - # password:: Password to use in conjunction with the above user name - # for SMTP authentication. + # password:: Password to use when sending email. # # password = "secret" # - # template_directory:: The source directory where all file attachments are pulled from - # All file attachments should be their relative path from this location, without a leading / + # template_directory:: Directory where email templates are stored. # - template_directory = raddb/mods_config/smtp + # All file attachments should be given as a relative path + # from this location. i.e. without a leading '/'. + # + template_directory = ${confdir}/mods_config/smtp/ # - # Attachments:: attachments with their relative path from template_directory - # There can be no leading / or .. + # Attachments:: File names to attach to the templates. + # + # The filenames are relative to `template_directory` # attachments = SMTP-Attachments[*] # - # envelope_address:: This is the address used to send the mail, - # Sent to the receiving server as MAIL FROM: - # sender_address will be defaulted to if this is not set + # envelope_address:: Set the `MAIL FROM:` + # + # If this is not set, `MAIL FROM` will be set from `sender_address`. # envelope_address = "postmaster@localhost" @@ -320,12 +322,20 @@ smtp { # set_date = yes # - # header:: This is where any other headers can be added to the email - # FROM, TO, and CC, should not be added here if their respective elements were set in the config - # If no DATE header is provided, one will be added showing time that the request was received(recommended) - # Non-standard mail headers may be set. Adhere to your MTA's documentation + # header:: Additional headers to add to the messages. + # + # Any `FROM`, `TO`, and `CC` should not be added here. They are set in the configuration items above. + # + # If no `DATE` header is provided, one will be added which + # shows the time that the request was sent. + # + # Non-standard mail headers may be set. Adhere to your MTA's + # documentation # header { + # + # Headers are added with the given names and values, in the order listed here. + # subject = "email subject" Message-ID = "950124.162336@example.com" # X-Originating-IP = "192.0.20.1"