#  -*- text -*-
#
#
#  $Id: 8d45d7857b685b8b05e0b87b440fb12851bf0f8e $

#######################################################################
#
#  = SMTP Module
#
#  The `smtp` module can perform two actions:
#
#  When called in the `authenticate` section, it validates a users
#  name and password from request attributes against an SMTP server
#  without sending a mail.
#
#  When called with the method `mail` it will send an email.
#
#  The module can optionally perform a tls handshake, enabled with
#  require_cert
#

smtp {
	#
	#  tls { ... }:: Configure the tls related items which control how
	#  FreeRADIUS connects to an SMTP server.
	#
	tls {
		#
		#  Certificate validation options
		#
		#  Specifies how the certificate(s) presented by the SMTP server are
		#  validated, and which certificates (if any) to send to that SMTP
		#  server.
		#
		#  The options here behave the same as the options in other `tls`
		#  sections in the server.
		#

		#
		#  certificate_file:: PEM formatted file containing the certificate
		#  we present to the SMTP server
		#
		#  Specifies a certificate and any intermediary CAs we should send
		#  to the SMTP server.
		#
		#  This file should usually contain the client certificate file
		#  first, then any intermediary signing CAs, shallowest (direct
		#  signee of the certificate_file) to deepest (signed directly by
		#  the root CA).
		#
#		certificate_file = /path/to/radius.pem

		#
		#  ca_file:: PEM formatted file containing the chain to validate the
		#  SMTP server's certificate.
		#
		#  Any certificate chain MUST be in order from server certificate
		#  (first in the file) to intermediary CAs (second) to Root CA (last
		#  in the file) as per RFC 4346 Section 7.4.2 (see certificate_list)
		#
		#  Providing a complete certificate chain here is the most common
		#  way of validating the certificate presented by an SMTP server.
		#
#		ca_file = "${certdir}/cacert.pem"

		#
		#  ca_issuer_file:: PEM formatted file containing the CA that signed
		#  the SMTP server's certificate.
		#
		#  Specifies the certificate which directly signed the certificate
		#  presented by the SMTPs server.
		#
		#  This configuration option can be used to prevent certificates
		#  passing validation which were signed by other intermediary CAs,
		#  or root CAs, in the trusted certificate chain.
		#
#		ca_issuer_file = "${certdir}/caissuer.pem"

		#
		#  ca_path:: A directory containing multiple root CA certs named by
		#  their hash.
		#
		#  This configuration option should only be used when the SMTP
		#  server being contacted is not known ahead of time (using a URL
		#  from an external source), and/or the CA used to sign the SMTP
		#  server certificate is unknown.
		#
		#  If not set, then whatever libcurl has as its default will be
		#  used, which typically will be the operating system's set of
		#  trusted CAs. This will be visible in the debug output when
		#  FreeRADIUS starts.
		#
#		ca_path = "${certdir}"

		#
		#  private_key_file:: PEM formatted file containing the private key
		#  for the specified `certificate_file`
		#
		#  This item must be specified if `certificate_file` is being used.
		#
#		private_key_file = /path/to/radius.key

		#
		#  private_key_password:: Password used to decrypt the
		#  `private_key_file`.
		#
#		private_key_password = "supersecret"

		#
		#  random_file:: Source of random data used for various
		#  cryptographic functions.
		#
#		random_file = /dev/urandom

		#
		#  check_cert:: Server certificate verification requirements.
		#
		#  May be one of:
		#
		#  [options="header,autowidth"]
		#  |===
		#  | Option | Description
		#  | `no`   | Server certificate can be signed by any CA or be self-signed.
		#  | `yes`  | Server certificate must be issued by one of the trusted CAs.
		#  |===
		#
		#  Default is `yes`
		#
#		check_cert = no

		#
		#  request_cert:: Options for controlling how the module requests
		#  TLS to the SMTP server.
		#
		#  May be one of:
		#
		#  [options="header,autowidth"]
		#  |===
		#  | Option | Description
		#  | `demand`   | Require ssl validation to accept login
		#  | `never`  | Do not try to establish ssl connection
		#  | `allow`  | Try to establish ssl connection, continue even if it cannot
		#  |===
		#
		#  default is 'allow'
		#
#		require_cert = allow

		#
		#  check_cert_cn:: Server certificate CN verification requirements.
		#
		#  May be one of:
		#
		#  [options="header,autowidth"]
		#  |===
		#  | Option | Description
		#  | `no`   | Server certificate CN can be any value.
		#  | `yes`  | Server certificate CN matches the host in the URI.
		#  |===
		#
		#  Default is `yes`
		#
#		check_cert_cn = no

		#
		#  extract_cert_attrs:: Extract OIDs from presented certificates as
		#  OIDs.
		#
		#  Default is `no`
		#
#		extract_cert_attrs = no
	}

	#
	#  uri:: URI which will be used for connecting to the SMTP server.
	#
	#  The `smtp` module uses Curl (https://curl.haxx.se/libcurl/) to
	#  implement 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`.
	#
	#  * `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`.
	#
	#  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 from the SMTP server.
	#
	timeout = 5s

	#
	#  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.
	#
	authenticate {
		#
		#  username:: The users name when performing SMTP authentication.
		#
#		username = User-Name

		#
		#  password_attribute:: The users password when performing SMTP
		#  authentication
		#
#		password = User-Password
	}

	#
	#  In most cases, the SMTP module will be used to send email.
	#

	#
	#  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 when sending email.
	#
#	password = "secret"

	#
	#  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 '/'.
	#
	template_directory = ${confdir}/mods_config/smtp/

	#
	#  Attachments:: File names to attach to the templates.
	#
	#  The filenames are relative to `template_directory`
	#
	attachments = SMTP-Attachments[*]

	#
	#  envelope_address:: Set the `MAIL FROM:<envelope_address>`
	#
	#  If this is not set, `MAIL FROM` will be set from `sender_address`.
	#
	envelope_address = "postmaster@localhost"

	#
	#  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.
	#
	sender_address = SMTP-Sender-Address[*]

	#
	#  recipients:: Email addresses to be set as recipients for the email
	#
	#  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.
	#
##	recipients = SMTP-Recipients[*]
##	recipients = SMTP-TO[*]
##	recipients = SMTP-CC[*]
##	recipients = SMTP-BCC[*]

	#
	#  to:: Set the body `TO` header.
	#
	#  If `recepients` is not set, then messages will be sent to the `TO`
	#  address.
	#
#	to = SMTP-TO[*]

	#
	#  cc:: Set the body `CC` header.
	#
	#  If `recepients` is not set, then messages will also be sent to the
	#  `CC` addresses.
	#
#	cc = SMTP-CC[*]

	#
	#  bcc:: Set the `BCC` recipients.
	#
	#  The local part may contain commas, the domain may not (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.
	#
#	bcc = SMTP-BCC[*]

	#
	#  set_date:: Adds a Date: to the header, set to the time the request
	#  is received Formatted as "Fri, 07 Aug 2020 00:57:37 -0400, (EDT)"
	#  May be one of:
	#
	#  [options="header,autowidth"]
	#  |===
	#  | Option | Description
	#  | `no`   | A Date: should be specified in the header, or left to the receiving mta
	#  | `yes`  | A Date is formatted and added (recommended)
	#  |===
	#
	#  Default is `yes`
	#
#	set_date = yes

	#
	#  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"
	}

	#
	#  connection { .. }:: Configure how connection handles are managed
	#  per thread.
	#
	connection {
		#
		#  Reusable connection handles are allocated in blocks. These
		#  parameters allow for tuning how that is done.
		#
		#  Since http requests are performed async, the settings here
		#  represent outstanding http requests per thread.
		#
		reuse {

			#
			#  min:: The minimum number of connection handles to keep
			#  allocated.
			#
			min = 10

			#
			#  max:: The maximum number of reusable connection handles to
			#  allocate.
			#
			#  Any requests to allocate a connection handle beyond this number
			#  will cause a temporary handle to be allocated. This is less
			#  efficient than the block allocation so `max` should be set to
			#  reflect the number of outstanding requests expected at peak
			#  load.
			max = 100

			#
			#  cleanup_interval:: How often to free un-used connection handles.
			#
			#  Every `cleanup_interval` a cleanup routine runs which will free
			#  any blocks of handles which are not in use, ensuring that at
			#  least `min` handles are kept.
			#
			cleanup_interval = 30s

		}
	}
}
