opensmtpd.texi 35 KB

  1. \input texinfo @c -*- texinfo -*-
  2. @c %**start of header
  3. @setfilename
  4. @settitle OpenSMTPD Service documentation
  5. @documentencoding UTF-8
  6. @documentlanguage en
  7. @c %**end of header
  8. @finalout
  9. @titlepage
  10. @title OpenSMTPD Service documentation
  11. @author Joshua Branson
  12. @end titlepage
  13. @contents
  14. @ifnottex
  15. @node Top
  16. @top OpenSMTPD Service documentation
  17. OpenSMTPD is an easy-to-use mail transfer agent (MTA). Its configuration file is
  18. throughly documented in @code{man 5 smtpd.conf}. OpenSMTPD @strong{listens} for incoming
  19. mail and @strong{matches} the mail to @strong{actions}. The following records represent those
  20. stages:
  21. @multitable {aaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  22. @item @strong{listens}
  23. @tab @code{<opensmtpd-interface}
  24. @item
  25. @tab @code{<opensmtpd-socket>}
  26. @item
  27. @tab
  28. @item @strong{matches}
  29. @tab @code{<opensmtpd-match>}
  30. @item
  31. @tab
  32. @item @strong{actions}
  33. @tab @code{<opensmtpd-local-delivery>}
  34. @item
  35. @tab @code{<opensmtpd-relay>}
  36. @end multitable
  37. Additionally, each @code{<opensmtpd-interface>} and
  38. @code{<opensmtpd-socket>} may use a list of
  39. @code{<opensmtpd-filter>}, and/or
  40. @code{<opensmtpd-filter-phase>} records to filter email/spam. Also
  41. numerous records' fieldnames use @code{<opensmtpd-table>} to hold lists
  42. or key value pairs of data.
  43. A simple example configuration is below:
  44. @example
  45. (let (( (opensmtpd-pki
  46. (domain "")
  47. (cert "file.cert")
  48. (key "file.key"))))
  49. (service opensmtpd-service-type
  50. (opensmtpd-configuration
  51. (interface (list
  52. (opensmtpd-interface
  53. (pki
  54. (opensmtpd-interface
  55. (pki
  56. (secure-connection "smtps"))))
  57. (matches (list
  58. (opensmtpd-match
  59. (action
  60. (opensmtpd-local-delivery
  61. (name "local-delivery"))))
  62. (opensmtpd-match
  63. (action
  64. (opensmtpd-relay
  65. (name "relay")))))))))
  66. @end example
  67. @itemize
  68. @item
  69. Scheme Variable: opensmtpd-service-type
  70. Service type for the OpenSMTPD (@uref{,}) email server. The
  71. value for this service type is a @code{<opensmtpd-configuration>} record.
  72. @item
  73. Data Type: opensmtpd-configuration
  74. Data type representing the configuration of OpenSMTPD@.
  75. @itemize
  76. @item
  77. @code{package} (default: @code{opensmtpd})
  78. The OpenSMTPD package to use.
  79. @item
  80. @code{config-file} (default: @code{#f})
  81. File-like object of the OpenSMTPD configuration file to use. By default it
  82. listens on the loopback network interface, and allows for mail from users
  83. and daemons on the local machine, as well as permitting email to remote
  84. servers. Run @code{man smtpd.conf} for more information.
  85. @item
  86. @code{bounce} (default: @code{(list "4h")})
  87. @code{bounce} is a list of strings (max length 4), which send warning messages
  88. to the envelope sender when temporary delivery failures cause a message to
  89. remain in the queue for longer than string delay. Each string delay
  90. parameter consists of a string beginning with a positive decimal integer
  91. and a unit 's', 'm', 'h', or 'd'. At most four delay parameters can be
  92. specified.
  93. @item
  94. @code{interface} (default: @code{(list (opensmtpd-interface))})
  95. @code{interface} is a list of @code{<opensmtpd-interface>} records.
  96. This list details what interfaces and ports OpenSMTPD listens on as well as
  97. other information.
  98. @item
  99. @code{socket} (default: @code{(opensmtpd-socket-configuration)})
  100. Listens for incoming connections on the Unix domain socket.
  101. @item
  102. @code{includes} (default: @code{#f})
  103. @code{includes} is a list of string filenames. Each filename's contents is
  104. additional configuration that is inserted into the top of the configuration
  105. file.
  106. @item
  107. @code{matches} default:
  108. @example
  109. (list (opensmtpd-match
  110. (action (opensmtpd-local-delivery
  111. (name "local")
  112. (method "mbox")))
  113. (for (opensmtpd-option
  114. (option "for local"))))
  115. (opensmtpd-match
  116. (action (opensmtpd-relay
  117. (name "outbound")))
  118. (from (opensmtpd-option
  119. (option "from local")))
  120. (for (opensmtpd-option
  121. (option "for any")))))
  122. @end example
  123. @code{matches} is a list of @code{<opensmtpd-match>} records, which
  124. @strong{matches} incoming mail and sends it to a correspending @strong{action}. The
  125. match records are evaluated sequentially, with the first match winning. If
  126. an incoming mail does not match any match records, then it is rejected.
  127. @end itemize
  128. @itemize
  129. @item
  130. @code{mta-max-deferred} (default: @code{100})
  131. When delivery to a given host is suspended due to temporary failures, cache
  132. at most number envelopes for that host such that they can be delivered as
  133. soon as another delivery succeeds to that host. The default is 100.
  134. @item
  135. @code{queue} (default: @code{#f})
  136. @code{queue} expects an @code{<opensmtpd-queue>} record. With it, one may
  137. compress and encrypt queue-ed emails as well as set the default expiration
  138. time for temporarily undeliverable messages.
  139. @item
  140. @code{smtp} (default: @code{#f})
  141. @code{smtp} expects an @code{<opensmtpd-smtp>} record, which lets one
  142. specifiy how large email may be along with other settings.
  143. @item
  144. @code{srs} (default: @code{#f})
  145. @code{srs} expects an @code{<opensmtpd-srs>} record, which lets one set
  146. up SRS, the Sender Rewritting Scheme.
  147. @end itemize
  148. @end itemize
  149. @itemize
  150. @item
  151. Data Type: opensmtpd-interface
  152. Data type representing the configuration of an
  153. @code{<opensmtpd-interface>}. Listen on the fieldname @code{interface} for
  154. incoming connections, using the same syntax as for ifconfig(8). The interface
  155. parameter may also be an string interface group, an string IP address, or a
  156. string domain name. Listening can optionally be restricted to a specific
  157. address fieldname @code{family}, which can be either ``inet4'' or ``inet6''.
  158. @itemize
  159. @item
  160. @code{interface} (default: ``lo'')
  161. The string interface to listen for incoming connections. These interface can
  162. usually be found by the command @code{ip link}.
  163. @item
  164. @code{family} (default: @code{#f})
  165. The string IP family to use. Valid strings are ``inet4'' or ``inet6''.
  166. @item
  167. @code{auth} (default: @code{#f})
  168. Support SMTPAUTH: clients may only start SMTP transactions after successful
  169. authentication. If @code{auth} is @code{#t}, then users are authenticated against
  170. their own normal login credentials. Alternatively @code{auth} may be an
  171. @code{<opensmtpd-table>} whose users are authenticated against
  172. their passwords.
  173. @item
  174. @code{auth-optional} (default: @code{#f})
  175. Support SMTPAUTH optionally: clients need not authenticate, but may do so.
  176. This allows the @code{<opensmtpd-interface>} to both accept
  177. incoming mail from untrusted senders and permit outgoing mail from
  178. authenticated users (using @code{<opensmtpd-match>} fieldname
  179. @code{auth}). It can be used in situations where it is not possible to listen on
  180. a separate port (usually the submission port, 587) for users to
  181. authenticate.
  182. @item
  183. @code{filters} (default: @code{#f})
  184. A list of one or many @code{<opensmtpd-filter>} or
  185. @code{<opensmtpd-filter-phase>} records. The filters are applied
  186. sequentially. These records listen and filter on connections handled by this
  187. listener.
  188. @item
  189. @code{hostname} (default: @code{#f})
  190. Use string ``hostname'' in the greeting banner instead of the default server
  191. name.
  192. @item
  193. @code{hostnames} (default: @code{#f})
  194. Override the server name for specific addresses. Use a
  195. @code{<opensmtpd-table>} containing a mapping of string IP
  196. addresses to hostnames. If the address on which the connection arrives
  197. appears in the mapping, the associated hostname is used.
  198. @item
  199. @code{mask-src} (default: @code{#f})
  200. If @code{#t}, then omit the from part when prepending “Received” headers.
  201. @item
  202. @code{disable-dsn} (default: @code{#f})
  203. When @code{#t}, then disable the DSN (Delivery Status Notification) extension.
  204. @item
  205. @code{pki} (default: @code{#f})
  206. For secure connections, use an @code{<opensmtpd-pki>}
  207. to prove a mail server's identity.
  208. @item
  209. @code{port} (default: @code{#f})
  210. Listen on the integer port instead of the default port of 25.
  211. @item
  212. @code{proxy-v2} (default: @code{#f})
  213. If @code{#t}, then support the PROXYv2 protocol, rewriting appropriately source
  214. address received from proxy.
  215. @item
  216. @code{received-auth} (default: @code{#f})
  217. If @code{#t}, then in “Received” headers, report whether the session was
  218. authenticated and by which local user.
  219. @item
  220. @code{senders} (default: @code{#f})
  221. Look up the authenticated user in the supplied
  222. @code{<opensmtpd-table>} to find the email addresses that user is
  223. allowed to submit mail as.
  224. @item
  225. @code{secure-connection} (default: @code{#f})
  226. This is a string of one of these options:
  227. @multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  228. @item ``smtps''
  229. @tab Support SMTPS, by default on port 465.
  230. @item
  231. @tab
  232. @item ``tls''
  233. @tab Support STARTTLS, by default on port 25.
  234. @item
  235. @tab
  236. @item ``tls-require-verify''
  237. @tab Like tls, but force clients to establish
  238. @item
  239. @tab a secure connection before being allowed to
  240. @item
  241. @tab start an SMTP transaction. With the verify
  242. @item
  243. @tab option, clients must also provide a valid
  244. @item
  245. @tab certificate to establish an SMTP session.
  246. @end multitable
  247. @item
  248. @code{tag} (default: @code{#f})
  249. Clients connecting to the listener are tagged with the given string tag.
  250. @end itemize
  251. @item
  252. Data Type: opensmtpd-socket
  253. Data type representing the configuration of an
  254. @code{<opensmtpd-socket>}. Listen for incoming SMTP
  255. connections on the Unix domain socket @samp{/var/run/smtpd.sock}. This is done by
  256. default, even if the directive is absent.
  257. @itemize
  258. @item
  259. @code{filters} (default: @code{#f})
  260. A list of one or many @code{<opensmtpd-filter>} or
  261. @code{<opensmtpd-filter-phase>} records. These filter incoming
  262. connections handled by this listener.
  263. @item
  264. @code{mask-src} (default: @code{#f})
  265. If @code{#t}, then omit the from part when prepending “Received” headers.
  266. @item
  267. @code{tag} (default: @code{#f})
  268. Clients connecting to the listener are tagged with the given string tag.
  269. @end itemize
  270. @item
  271. Data Type: opensmtpd-match
  272. This data type represents the configuration of an
  273. @code{<opensmtpd-match>} record.
  274. If at least one mail envelope matches the options of one match record, receive
  275. the incoming message, put a copy into each matching envelope, and atomically
  276. save the envelopes to the mail spool for later processing by the respective
  277. @code{<opensmtpd-action-configuration>} found in fieldname @code{action}.
  278. @itemize
  279. @item
  280. @code{action} (default: @code{#f})
  281. If mail matches this match configuration, then do this action. Valid values
  282. include @code{<opensmtpd-local-delivery>} or
  283. @code{<opensmtpd-relay>}.
  284. @item
  285. @code{options} (default: @code{#f}) @code{<opensmtpd-option>}
  286. The fieldname 'option' is a list of unique
  287. @code{<opensmtpd-option>} records.
  288. Each @code{<opensmtpd-option>} record's fieldname 'option' has
  289. some mutually exclusive options: there can be only one ``for'' and only one
  290. ``from'' option.
  291. @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  292. @headitem for
  293. @tab from
  294. @item only use one of the following:
  295. @tab only use one of the following:
  296. @item ``for any''
  297. @tab ``from any''
  298. @item ``for local''
  299. @tab ``from auth''
  300. @item ``for domain''
  301. @tab ``from local''
  302. @item ``for rcpt-to''
  303. @tab ``from mail-from''
  304. @item
  305. @tab ``from socket''
  306. @item
  307. @tab ``from src''
  308. @end multitable
  309. Additionally, some options require additional data via their fieldname
  310. @code{data}. The following list will explain the below syntax.
  311. @itemize
  312. @item
  313. ``for any''
  314. @example
  315. (opensmtpd-option
  316. (option "for any"))
  317. @end example
  318. @item
  319. ``for rcpt'' domain | <list table>
  320. @example
  321. (opensmtpd-option
  322. (option "for rcpt")
  323. (data "domain"))
  324. @end example
  325. OR
  326. @example
  327. (opensmtpd-option
  328. (option "for rcpt")
  329. (data (list "" "")))
  330. @end example
  331. @end itemize
  332. The following matching options are supported and can all be negated (via not
  333. #t). The options that support a table (anything surrounded with '<' and '>'
  334. eg: <table>), also support specifying regex via (regex #t).
  335. @itemize
  336. @item
  337. @code{for any}
  338. Specify that session may address any destination.
  339. @item
  340. @code{for local}
  341. Specify that session may address any local domain. This is the default,
  342. and may be omitted.
  343. @item
  344. @code{for domain _domain_ | <domain>}
  345. Specify that session may address the string or list table domain.
  346. @item
  347. @code{for rcpt-to _recipient_ | <recipient>}
  348. Specify that session may address the string or list table recipient.
  349. @item
  350. @code{from any}
  351. Specify that session may originate from any source.
  352. @item
  353. @code{from auth}
  354. Specify that session may originate from any authenticated user, no matter
  355. the source IP address.
  356. @item
  357. @samp{from auth _user_ | <user>}
  358. Specify that session may originate from authenticated user or user list
  359. user, no matter the source IP address.
  360. @item
  361. @code{from local}
  362. Specify that session may only originate from a local IP address, or from
  363. the local enqueuer. This is the default, and may be omitted.
  364. @item
  365. @samp{from mail-from _sender_ | <sender>}
  366. Specify that session may originate from sender or table sender, no
  367. matter the source IP address.
  368. @item
  369. @samp{from rdns}
  370. Specify that session may only originate from an IP address that resolves
  371. to a reverse DNS@.
  372. @item
  373. @samp{from rdns _hostname_ | <hostname>}
  374. Specify that session may only originate from an IP address that resolves
  375. to a reverse DNS matching string or list string hostname.
  376. @item
  377. @samp{from socket}
  378. Specify that session may only originate from the local enqueuer.
  379. @item
  380. @samp{from src _address_ | <address>}
  381. Specify that session may only originate from string or list table address
  382. which can be a specific address or a subnet expressed in CIDR-notation.
  383. @item
  384. @samp{auth}
  385. Matches transactions which have been authenticated.
  386. @item
  387. @samp{auth _username_ | <username>}
  388. Matches transactions which have been authenticated for user or user list
  389. username.
  390. @item
  391. @samp{helo _helo-name_ | <helo-name>}
  392. Specify that session's HELO / EHLO should match the string or list table
  393. helo-name.
  394. @item
  395. @samp{mail-from _sender_ | <sender>}
  396. Specify that transactions's MAIL FROM should match the string or list
  397. table sender.
  398. @item
  399. @samp{rcpt-to _recipient_ | <recipient>}
  400. Specify that transaction's RCPT TO should match the string or list table
  401. recipient.
  402. @item
  403. @samp{tag tag}
  404. Matches transactions tagged with the given tag.
  405. @item
  406. @samp{tls}
  407. Specify that transaction should take place in a TLS channel.
  408. @end itemize
  409. Here is a simple example that rejects email from the domains @samp{}
  410. or @samp{}:
  411. ,#+BEGIN@math{_SRC} scheme
  412. (opensmtpd-option
  413. (not #t)
  414. (regex #f)
  415. (option ``for domain'')
  416. (data (opensmtpd-table
  417. (name ``domain-table'')
  418. (data (list ``'' ``'')))))
  419. #+END@math{_SRC}
  420. @end itemize
  421. @end itemize
  422. @itemize
  423. @item
  424. Data Type: opensmtpd-local-delivery
  425. This data type represents the configuration of an
  426. @code{<opensmtpd-local-delivery>} record.
  427. @itemize
  428. @item
  429. @code{name} (default: @code{#f})
  430. @code{name} is the string name of the relay action.
  431. @item
  432. @code{method} (default: @code{"mbox"})
  433. The email delivery option. Valid options are:
  434. @itemize
  435. @item
  436. @code{"mbox"}
  437. Deliver the message to the user's mbox with mail.local(8).
  438. @item
  439. @code{"expand-only"}
  440. Only accept the message if a delivery method was specified in an aliases
  441. or .forward file.
  442. @item
  443. @code{"forward-only"}
  444. Only accept the message if the recipient results in a remote address after
  445. the processing of aliases or forward file.
  446. @item
  447. @code{<opensmtpd-lmtp-configuration>}
  448. Deliver the message to an LMTP server at
  449. @code{<opensmtpd-lmtp-configuration>}'s fieldname @code{destination}. The location
  450. may be expressed as string host:port or as a UNIX socket. Optionally,
  451. @code{<opensmtpd-lmtp-configuration>}'s fieldname @code{rcpt-to} might be specified
  452. to use the recipient email address (after expansion) instead of the local
  453. user in the LMTP session as RCPT TO@.
  454. @item
  455. @code{<opensmtpd-maildir>}
  456. Deliver the message to the maildir in
  457. @code{<opensmtpd-maildir>}'s fieldname @code{pathname} if specified,
  458. or by default to @samp{~/Maildir}.
  459. The pathname may contain format specifiers that are expanded before use
  460. (see the below section about Format Specifiers).
  461. If @code{<opensmtpd-maildir>}'s record fieldname @code{junk} is @code{#t},
  462. then message will be moved to the ‘Junk’ folder if it contains a positive
  463. ‘X-Spam’ header. This folder will be created under fieldname @code{pathname} if
  464. it does not yet exist.
  465. @item
  466. @code{<opensmtpd-mda>}
  467. Delegate the delivery to the @code{<opensmtpd-mda>}'s fieldname
  468. @code{command} (type string) that receives the message on its standard input.
  469. The @code{command} may contain format specifiers that are expanded before use
  470. (see Format Specifiers).
  471. @end itemize
  472. @item
  473. @code{alias} (default: @code{#f})
  474. Use the mapping table for aliases expansion. @code{alias} is an
  475. @code{<opensmtpd-table>}.
  476. @item
  477. @code{ttl} (default: @code{#f})
  478. @code{ttl} is a string specify how long a message may remain in the queue. It's
  479. format is @samp{n@{s|m|h|d@}}. eg: ``4m'' is four minutes.
  480. @item
  481. @code{user} (default: @code{#f} )
  482. @code{user} is the string username for performing the delivery, to be looked up
  483. with getpwnam(3).
  484. This is used for virtual hosting where a single username is in charge of
  485. handling delivery for all virtual users.
  486. This option is not usable with the mbox delivery method.
  487. @item
  488. @code{userbase} (default: @code{#f})
  489. @code{userbase} is an @code{<opensmtpd-table>} record for mapping user
  490. lookups instead of the getpwnam(3) function.
  491. The fieldnames @code{user} and @code{userbase} are mutually exclusive.
  492. @item
  493. @code{virtual} (default: @code{#f})
  494. @code{virtual} is an @code{<opensmtpd-table>} record is used for virtual
  495. expansion.
  496. @end itemize
  497. @item
  498. Data Type: opensmtpd-relay
  499. This data type represents the configuration of an
  500. @code{<opensmtpd-relay>} record.
  501. @itemize
  502. @item
  503. @code{name} (default: @code{#f})
  504. @code{name} is the string name of the relay action.
  505. @item
  506. @code{backup} (default: @code{#f})
  507. When @code{#t}, operate as a backup mail exchanger delivering messages to any
  508. mail exchanger with higher priority.
  509. @item
  510. @code{backup-mx} (default: @code{#f})
  511. Operate as a backup mail exchanger delivering messages to any mail exchanger
  512. with higher priority than mail exchanger identified as string name.
  513. @item
  514. @code{helo} (default: @code{#f})
  515. Advertise string heloname as the hostname to other mail exchangers during
  516. the HELO phase.
  517. @item
  518. @code{helo-src} (default: @code{#f})
  519. Use the mapping @code{<openmstpd-table-configuration>} to look up a hostname
  520. matching the source address, to advertise during the HELO phase.
  521. @item
  522. @code{domain} (default: @code{#f})
  523. Do not perform MX lookups but look up destination domain in an
  524. @code{<opensmtpd-table>} and use matching relay url as relay host.
  525. @item
  526. @code{host} (default: @code{#f})
  527. Do not perform MX lookups but relay messages to the relay host described by
  528. the string relay-url. The format for relay-url is
  529. @samp{[proto://[label@@]]host[:port]}. The following protocols are available:
  530. @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  531. @item smtp
  532. @tab Normal SMTP session with opportunistic STARTTLS (the default).
  533. @item smtp+tls
  534. @tab Normal SMTP session with mandatory STARTTLS@.
  535. @item smtp+notls
  536. @tab Plain text SMTP session without TLS@.
  537. @item lmtp
  538. @tab LMTP session. port is required.
  539. @item smtps
  540. @tab SMTP session with forced TLS on connection, default port is
  541. @item
  542. @tab 465.
  543. @end multitable
  544. Unless noted, port defaults to 25.
  545. The label corresponds to an entry in a credentials table, as documented in
  546. @samp{table(5)}. It is used with the @samp{"smtp+tls"} and @samp{"smtps"} protocols for
  547. authentication. Server certificates for those protocols are verified by
  548. default.
  549. @item
  550. @code{pki} (default: @code{#f})
  551. For secure connections, use the certificate associated with
  552. @code{<opensmtpd-pki>} (declared in a pki directive) to prove the
  553. client's identity to the remote mail server.
  554. @item
  555. @code{srs} (default: @code{#f})
  556. If @code{#t}, then when relaying a mail resulting from a forward, use the Sender
  557. Rewriting Scheme to rewrite sender address.
  558. @item
  559. @code{tls} (default: @code{#f}) boolean or string ``no-verify''
  560. When @code{#t}, Require TLS to be used when relaying, using mandatory STARTTLS by
  561. default. When used with a smarthost, the protocol must not be
  562. @samp{"smtp+notls://"}. When string @code{"no-verify"}, then do not require a valid
  563. certificate.
  564. @item
  565. @code{auth} (default: @code{#f}) @code{<opensmtpd-table>}
  566. Use the alist @code{<opensmtpd-table>} for connecting to relay-url
  567. using credentials. This option is usable only with fieldname @code{host} option.
  568. @item
  569. @code{mail-from} (default: @code{#f}) string
  570. Use the string mailaddress as MAIL FROM address within the SMTP transaction.
  571. @item
  572. @code{src} (default: @code{#f}) string | @code{<opensmtpd-table>}
  573. Use the string or @code{<opensmtpd-table>} sourceaddr for the
  574. source IP address, which is useful on machines with multiple interfaces. If
  575. the list contains more than one address, all of them are used in such a way
  576. that traffic is routed as efficiently as possible.
  577. @end itemize
  578. @item
  579. Data Type: opensmtpd-filter
  580. @@c The code does NOT actually support these things yet.
  581. This data type represents the configuration of an
  582. @code{<opensmtpd-filter>}. This is the filter record one should use
  583. if they want to use an external package to filter email eg: rspamd or
  584. spamassassin.
  585. @itemize
  586. @item
  587. @code{name} (default: @code{#f})
  588. The string name of the filter.
  589. @item
  590. @code{proc} (default: @code{#f})
  591. The string command or process name. If @code{proc-exec} is @code{#t}, @code{proc} is
  592. treated as a command to execute. Otherwise, it is a process name.
  593. @item
  594. @code{proc-exec} (default: @code{#f})
  595. @end itemize
  596. @item
  597. Data Type: opensmtpd-filter-phase
  598. This data type represents the configuration of an
  599. @code{<opensmtpd-filter-phase>}.
  600. In a regular workflow, smtpd(8) may accept or reject a message based only on
  601. the content of envelopes. Its decisions are about the handling of the message,
  602. not about the handling of an active session.
  603. Filtering extends the decision making process by allowing smtpd(8) to stop at
  604. each phase of an SMTP session, check that options are met, then decide if a
  605. session is allowed to move forward.
  606. With filtering via an @code{<opensmtpd-filter-phase>} record, a
  607. session may be interrupted at any phase before an envelope is complete. A
  608. message may also be rejected after being submitted, regardless of whether the
  609. envelope was accepted or not.
  610. @itemize
  611. @item
  612. @code{name} (default: @code{#f})
  613. The string name of the filter phase.
  614. @item
  615. @code{phase-name} (default: @code{#f})
  616. The string name of the phase. Valid values are:
  617. @multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  618. @item ``connect''
  619. @tab upon connection, before a banner is displayed
  620. @item ``helo''
  621. @tab after HELO command is submitted
  622. @item ``ehlo''
  623. @tab after EHLO command is submitted
  624. @item ``mail-from''
  625. @tab after MAIL FROM command is submitted
  626. @item ``rcpt-to''
  627. @tab after RCPT TO command is submitted
  628. @item ``data''
  629. @tab after DATA command is submitted
  630. @item ``commit''
  631. @tab after message is fully is submitted
  632. @end multitable
  633. @item
  634. @code{options} (default @code{#f})
  635. A list of unique @code{<opensmtpd-option>} records.
  636. At each phase, various options, specified by a list of
  637. @code{<opensmtpd-option>}, may be checked. The
  638. @code{<opensmtpd-option>}'s fieldname 'option' values of: ``fcrdns'',
  639. ``rdns'', and ``src'' data are available in all phases, but other data must have
  640. been already submitted before they are available. Options with a @samp{<table>}
  641. next to them require the @code{<opensmtpd-option>}'s fieldname
  642. @code{data} to be an @code{<opensmtpd-table>}. These are the available
  643. options:
  644. @multitable {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  645. @item fcrdns
  646. @tab forward-confirmed reverse DNS is valid
  647. @item rdns
  648. @tab session has a reverse DNS
  649. @item rdns <table>
  650. @tab session has a reverse DNS in table
  651. @item src <table>
  652. @tab source address is in table
  653. @item helo <table>
  654. @tab helo name is in table
  655. @item auth
  656. @tab session is authenticated
  657. @item auth <table>
  658. @tab session username is in table
  659. @item mail-from <table>
  660. @tab sender address is in table
  661. @item rcpt-to <table>
  662. @tab recipient address is in table
  663. @end multitable
  664. These conditions may all be negated by setting
  665. @code{<opensmtpd-option>}'s fieldname @code{not} to @code{#t}.
  666. Any conditions that require a table may indicate that tables include regexs
  667. setting @code{<opensmtpd-option>}'s fieldname @code{regex} to @code{#t}.
  668. @item
  669. @code{decision}
  670. A string decision to be taken. Some decisions require an @code{message} or
  671. @code{value}. Valid strings are:
  672. @multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  673. @headitem ``bypass''
  674. @tab the session or transaction bypasses filters
  675. @item ``disconnect'' message
  676. @tab the session is disconnected with message
  677. @item ``junk''
  678. @tab the session or transaction is junked, i.e., an
  679. @item
  680. @tab ‘X-Spam: yes’ header is added to any messages
  681. @item ``reject'' message
  682. @tab the command is rejected with message
  683. @item ``rewrite'' value
  684. @tab the command parameter is rewritten with value
  685. @end multitable
  686. Decisions that involve a message require that the message be RFC valid,
  687. meaning that they should either start with a 4xx or 5xx status code.
  688. Descisions can be taken at any phase, though junking can only happen before
  689. a message is committed.
  690. @item
  691. @code{message} (default @code{#f})
  692. A string message beginning with a 4xx or 5xx status code.
  693. @item
  694. @code{value} (default: @code{#f})
  695. A number value. @code{value} and @code{message} are mutually exclusive.
  696. @end itemize
  697. @item
  698. Data Type: opensmtpd-option
  699. This data type represents the configuration of an
  700. @code{<opensmtpd-option>}, which is used by
  701. @code{<opensmtpd-filter-phase>} and @code{<opensmtpd-match>}
  702. to match various options for email.
  703. @itemize
  704. @item
  705. @code{conditition} (default @code{#f})
  706. A string option to be taken. Some options require a string or an
  707. @code{<opensmtpd-table>} via the fieldname data. When the option
  708. record is used inside of an @code{<opensmtpd-filter-phase>}, then
  709. valid strings are:
  710. At each phase, various options may be matched. The fcrdns, rdns, and src
  711. data are available in all phases, but other data must have been already
  712. submitted before they are available.
  713. @multitable {aaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  714. @item ``fcrdns''
  715. @tab forward-confirmed reverse DNS is valid
  716. @item ``rdns''
  717. @tab session has a reverse DNS
  718. @item ``rdns'' <table>
  719. @tab session has a reverse DNS in table
  720. @item ``src'' <table>
  721. @tab source address is in table
  722. @item ``helo'' <table>
  723. @tab helo name is in table
  724. @item ``auth''
  725. @tab session is authenticated
  726. @item ``auth'' <table>
  727. @tab session username is in table
  728. @item ``mail-from'' <table>
  729. @tab sender address is in table
  730. @item ``rcpt-to'' <table>
  731. @tab recipient address is in table
  732. @end multitable
  733. When @code{<opensmtpd-option>} is used inside of an
  734. @code{<opensmtpd-match>}, then valid strigs for fieldname @code{option}
  735. are: ``for'', ``for any'', ``for local'', ``for domain'', ``for rcpt-to'', ``from any''
  736. ``from auth'', ``from local'', ``from mail-from'', ``from rdns'', ``from socket'',
  737. ``from src'', ``auth'', ``helo'', ``mail-from'', ``rcpt-to'', ``tag'', or ``tls''.
  738. @item
  739. @code{data} (default @code{#f}) @code{<opensmtpd-table>}
  740. Some options require a table to be present. One would specify that table
  741. here.
  742. @item
  743. @code{regex} (default: @code{#f}) boolean
  744. Any options using a table may indicate that tables hold regex by
  745. prefixing the table name with the keyword regex.
  746. @item
  747. @code{not} (default: @code{#f}) boolean
  748. When @code{#t}, this option record is negated.
  749. @end itemize
  750. @item
  751. Data Type: opensmtpd-table
  752. This data type represents the configuration of an
  753. @code{<opensmtpd-table>}.
  754. @itemize
  755. @item
  756. @code{name} (default @code{#f})
  757. @code{name} is the name of the @code{<opensmtpd-table>} record.
  758. @item
  759. @code{data} (default: @code{#f})
  760. @code{data} expects a list of strings or an alist, which is a list of
  761. cons cells. eg: @code{(data (list ("james" . "password")))} OR
  762. @code{(data (list ("" "")))}.
  763. @end itemize
  764. @item
  765. Data Type: opensmtpd-pki
  766. This data type represents the configuration of an
  767. @code{<opensmtpd-pki>}.
  768. @itemize
  769. @item
  770. @code{domain} (default @code{#f})
  771. @code{domain} is the string name of the @code{<opensmtpd-pki>} record.
  772. @item
  773. @code{cert} (default: @code{#f})
  774. @code{cert} (default: @code{#f})
  775. @code{cert} is the string certificate filename to use for this pki.
  776. @item
  777. @code{key} (default: @code{#f})
  778. @code{key} is the string certificate falename to use for this pki.
  779. @item
  780. @code{dhe} (default: @code{"none"})
  781. Specify the DHE string parameter to use for DHE cipher suites with host
  782. pkiname. Valid parameter values are ``none'', ``legacy'', or ``auto''. For ``legacy'', a
  783. fixed key length of 1024 bits is used, whereas for ``auto'', the key length is
  784. determined automatically. The default is ``none'', which disables DHE cipher
  785. suites.
  786. @end itemize
  787. @item
  788. Data Type: opensmtpd-maildir
  789. @itemize
  790. @item
  791. @code{pathname} (default: @code{"~/Maildir"})
  792. Deliver the message to the maildir if pathname if specified, or by default
  793. to @samp{~/Maildir}.
  794. The pathname may contain format specifiers that are expanded before use
  796. @item
  797. @code{junk} (default: @code{#f})
  798. If the junk argument is @code{#t}, then the message will be moved to the @samp{‘Junk’}
  799. folder if it contains a positive @samp{‘X-Spam’} header. This folder will be
  800. created under pathname if it does not yet exist.
  801. @end itemize
  802. @item
  803. Data Type: opensmtpd-mda
  804. @itemize
  805. @item
  806. @code{name}
  807. The string name for this MDA command.
  808. @item
  809. @code{command}
  810. Delegate the delivery to a command that receives the message on its standard
  811. input.
  812. The command may contain format specifiers that are expanded before use (see
  814. @end itemize
  815. @item
  816. Data Type: opensmtpd-queue
  817. @itemize
  818. @item
  819. @code{compression} (default @code{#f})
  820. Store queue files in a compressed format. This may be useful to save disk
  821. space.
  822. @item
  823. @code{encryption} (default @code{#f})
  824. Encrypt queue files with EVP@math{_aes}@math{_256}@math{_gcm}(3). If no key is specified, it is
  825. read with getpass(3). If the string stdin or a single dash (‘-’) is given
  826. instead of a key, the key is read from the standard input.
  827. @item
  828. @code{ttl-delay} (default @code{#f})
  829. Set the default expiration time for temporarily undeliverable messages,
  830. given as a positive decimal integer followed by a unit s, m, h, or d. The
  831. default is four days (``4d'').
  832. @end itemize
  833. @end itemize
  834. @itemize
  835. @item
  836. Data Type: opensmtpd-smtp
  837. Data type representing an @code{<opensmtpd-smtp>} record.
  838. @itemize
  839. @item
  840. @code{ciphers} (default: @code{#f})
  841. Set the control string for SSL@math{_CTX}@math{_set}@math{_cipher}@math{_list}(3). The default is
  842. ``HIGH:!aNULL:!MD5''.
  843. @item
  844. @code{limit-max-mails} (default: @code{100})
  845. Limit the number of messages to count for each sessio
  846. @end itemize
  847. @end itemize
  848. @itemize
  849. @item
  850. @code{limit-max-rcpt} (default: @code{1000})
  851. Limit the number of recipients to count for each transaction.
  852. @item
  853. @code{max-message-size} (default: @code{35M})
  854. Reject messages larger than size, given as a positive number of bytes or as
  855. a string to be parsed with scan@math{_scaled}(3).
  856. @item
  857. @code{sub-addr-delim character} (default: @code{+})
  858. When resolving the local part of a local email address, ignore the ASCII
  859. character and all characters following it. This is helpful for email
  860. filters. @samp{""} is the same email address as
  861. @samp{""}. BUT an email filter can filter emails addressed to first
  862. email address into a 'Bills' email folder.
  863. @end itemize
  864. @itemize
  865. @item
  866. Data Type: opensmtpd-srs
  867. @itemize
  868. @item
  869. @code{key} (default: @code{#f})
  870. Set the secret key to use for SRS, the Sender Rewriting Scheme.
  871. @item
  872. @code{backup-key} (default: @code{#f})
  873. Set a backup secret key to use as a fallback for SRS@. This can be used to
  874. implement SRS key rotation.
  875. @item
  876. @code{ttl-delay} (default: @code{"4d"})
  877. Set the time-to-live delay for SRS envelopes. After this delay, a bounce
  878. reply to the SRS address will be discarded to limit risks of forged
  879. addresses.
  880. @end itemize
  881. @item
  882. Format Specifiers
  883. Some configuration records support expansion of their parameters at
  884. runtime. Such records (for example
  885. @code{<opensmtpd-maildir>}, @code{<opensmtpd-mda>}) may use
  886. format specifiers which are expanded before delivery or relaying. The
  887. following formats are currently supported:
  888. @multitable {aaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  889. @item @samp{%@{sender@}}
  890. @tab sender email address, may be empty string
  891. @item @samp{%@{sender.user@}}
  892. @tab user part of the sender email address, may be empty
  893. @item @samp{%@{sender.domain@}}
  894. @tab domain part of the sender email address, may be empty
  895. @item @samp{%@{rcpt@}}
  896. @tab recipient email address
  897. @item @samp{%@{rcpt.user@}}
  898. @tab user part of the recipient email address
  899. @item @samp{%@{rcpt.domain@}}
  900. @tab domain part of the recipient email address
  901. @item @samp{%@{dest@}}
  902. @tab recipient email address after expansion
  903. @item @samp{%@{dest.user@}}
  904. @tab user part after expansion
  905. @item @samp{%@{dest.domain@}}
  906. @tab domain part after expansion
  907. @item @samp{%@{user.username@}}
  908. @tab local user
  909. @item @samp{%@{}}
  910. @tab home directory of the local user
  911. @item @samp{%@{mbox.from@}}
  912. @tab name used in mbox From separator lines
  913. @item @samp{%@{mda@}}
  914. @tab mda command, only available for mda wrappers
  915. @end multitable
  916. Expansion formats also support partial expansion using the optional bracket notations
  917. with substring offset. For example, with recipient domain @samp{“”}:
  918. @multitable {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaa}
  919. @item @samp{%@{rcpt.domain[0]@}}
  920. @tab expands to “e”
  921. @item @samp{%@{rcpt.domain[1]@}}
  922. @tab expands to “x”
  923. @item @samp{%@{rcpt.domain[8:]@}}
  924. @tab expands to “org”
  925. @item @samp{%@{rcpt.domain[-3:]@}}
  926. @tab expands to “org”
  927. @item @samp{%@{rcpt.domain[0:6]@}}
  928. @tab expands to “example”
  929. @item @samp{%@{rcpt.domain[0:-4]@}}
  930. @tab expands to “example”
  931. @end multitable
  932. In addition, modifiers may be applied to the token. For example, with recipient
  933. @samp{“”}:
  934. @multitable {aaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  935. @item @samp{%@{rcpt:lowercase@}}
  936. @tab expands to “”
  937. @item @samp{%@{rcpt:uppercase@}}
  938. @tab expands to “USER+TAG@@EXAMPLE.ORG”
  939. @item @samp{%@{rcpt:strip@}}
  940. @tab expands to “”
  941. @item @samp{%@{rcpt:lowercasestrip@}}
  942. @tab expands to “”
  943. @end multitable
  944. For security concerns, expanded values are sanitized and potentially dangerous
  945. characters are replaced with ‘:’. In situations where they are desirable, the
  946. “raw” modifier may be applied. For example, with recipient
  947. @samp{“user+t?”}:
  948. @multitable {aaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  949. @item @samp{%@{rcpt@}}
  950. @tab expands to “”
  951. @item @samp{%@{rcpt:raw@}}
  952. @tab expands to “user+t?”
  953. @end multitable
  954. @end itemize
  955. @end ifnottex
  956. @bye