opensmtpd-records-documentation.txt 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889
  1. OpenSMTPD Service .................
  2. -- Scheme Variable: opensmtpd-service-type
  3. OpenSMTPD is an easy-to-use mail transfer agent (MTA). OpenSMTPD
  4. *listens* for incoming mail and *matches* the mail to *actions*.
  5. The following records represent those stages:
  6. *listens* ‘<opensmtpd-interface>’
  7. ‘<opensmtpd-socket>’
  8. *matches* ‘<opensmtpd-match>’
  9. *actions* ‘<opensmtpd-local-delivery>’
  10. ‘<opensmtpd-relay>’
  11. Additionally, each ‘<opensmtpd-interface>’ and ‘<opensmtpd-socket>’
  12. may use a list of ‘<opensmtpd-filter>’, and/or
  13. ‘<opensmtpd-filter-phase>’ records to filter email/spam. Also
  14. numerous records’ fieldnames use ‘<opensmtpd-table>’ records to
  15. hold lists or key value pairs of data. Be sure to read the
  16. ‘<opensmtpd-table>’ section to learn the differance between a
  17. ‘mapping table’ and a ‘list table’.
  18. Finally, both ‘<opensmtpd-match>’ and ‘<opensmtpd-filter-phase>’
  19. use ‘<opensmtpd-option>’ to configure various options.
  20. A simple example opensmtpd configuration is below:
  21. (let ((smtp.gnu.org (opensmtpd-pki
  22. (domain "smtp.gnu.org")
  23. (cert "file.cert")
  24. (key "file.key"))))
  25. (service opensmtpd-service-type
  26. (opensmtpd-configuration
  27. (interfaces (list
  28. (opensmtpd-interface
  29. (pki smtp.gnu.org))
  30. (opensmtpd-interface
  31. (pki smtp.gnu.org)
  32. (secure-connection "smtps"))))
  33. (matches (list
  34. (opensmtpd-match
  35. (action
  36. (opensmtpd-local-delivery
  37. (name "local-delivery"))))
  38. (opensmtpd-match
  39. (action
  40. (opensmtpd-relay
  41. (name "relay")))))))))
  42. -- Data Type: opensmtpd-configuration
  43. Data type representing the configuration of opensmtpd.
  44. ‘package’ (default: OPENSMTPD)
  45. Package object of the OpenSMTPD server.
  46. ‘config-file’ (default: ‘%default-opensmtpd-config-file’)
  47. File-like object of the OpenSMTPD configuration file to use.
  48. By default it listens on the loopback network interface, and
  49. allows for mail from users and daemons on the local machine,
  50. as well as permitting email to remote servers. Run ‘man
  51. smtpd.conf’ for more information.
  52. ‘bounce’ (default: ‘(list "4h")’)
  53. ‘bounce’ is a list of strings, which send warning messages to
  54. the envelope sender when temporary delivery failures cause a
  55. message to remain in the queue for longer than a specified
  56. delay. Each delay option is a string parameter beginning with
  57. a positive decimal integer and a unit, which can be ’s’, ’m’,
  58. ’h’, or ’d’. At most four delay parameters can be specified.
  59. ‘interfaces’ default:
  60. (list
  61. (opensmtpd-interface
  62. (interface "lo")
  63. (port 25)))
  64. ‘interfaces’ is a list of ‘<opensmtpd-interface>’ records.
  65. This list details what interfaces and ports OpenSMTPD listens
  66. on as well as other options.
  67. ‘socket’ (default: ‘(opensmtpd-socket)’)
  68. Listens for incoming connections on the Unix domain socket.
  69. ‘includes’ (default: ‘#f’)
  70. ‘includes’ is a list of string filenames. Each filename’s
  71. contents is additional configuration that is inserted into the
  72. top of the configuration file. Run ‘man smtpd.conf’ for more
  73. information.
  74. ‘matches’ default:
  75. (list (opensmtpd-match
  76. (action (opensmtpd-local-delivery
  77. (name "local")
  78. (method "mbox")
  79. (options
  80. (list
  81. (opensmtpd-option
  82. (option "for local")))))))
  83. (opensmtpd-match
  84. (action (opensmtpd-relay
  85. (name "outbound")))
  86. (options
  87. (list
  88. (opensmtpd-option
  89. (option "from local"))
  90. (opensmtpd-option
  91. (option "for any"))))))
  92. ‘matches’ is a list of ‘<opensmtpd-match>’ records, which
  93. matches incoming mail and sends it to a correspending action.
  94. The match records are evaluated sequentially, with the first
  95. match winning. Therefore _the order that you arrange your
  96. matches is important_. It’s a good idea to put specific
  97. matches first and an all emcompassing match (like ‘(option
  98. "for any")’) *last*. If an incoming mail does not match any
  99. match records, then it is rejected.
  100. ‘mta-max-deferred’ (default: ‘100’)
  101. When delivery to a given host is suspended due to temporary
  102. failures, cache at most number envelopes for that host such
  103. that they can be delivered as soon as another delivery
  104. succeeds to that host. The default is 100.
  105. ‘queue’ (default: ‘#f’)
  106. ‘queue’ expects an ‘<opensmtpd-queue>’ record. With it, one
  107. may compress and encrypt queue-ed emails as well as set the
  108. default expiration time for temporarily undeliverable
  109. messages.
  110. ‘smtp’ (default: ‘#f’)
  111. ‘smtp’ expects an ‘<opensmtpd-smtp>’ record, which lets one
  112. specifiy how large email may be along with other settings.
  113. ‘srs’ (default: ‘#f’)
  114. ‘srs’ expects an ‘<opensmtpd-srs>’ record, which lets one set
  115. up SRS, the Sender Rewritting Scheme.
  116. ‘setgid-commands?’ (default: ‘#t’)
  117. Make the following commands setgid to ‘smtpq’ so they can be
  118. executed: ‘smtpctl’, ‘sendmail’, ‘send-mail’, ‘makemap’,
  119. ‘mailq’, and ‘newaliases’. *Note Setuid Programs::, for more
  120. information on setgid programs.
  121. • Data Type: opensmtpd-interface Data type representing the
  122. configuration of an ‘<opensmtpd-interface>’. It listens on the
  123. fieldname ‘interface’ for incoming connections, using the same
  124. syntax as ‘ifconfig’. The interface parameter may also be an
  125. string interface group, an string IP address, or a string domain
  126. name. Listening can optionally be restricted to a specific address
  127. via the fieldname ‘family’, which can be either ‘"inet4"’ or
  128. ‘"inet6"’.
  129. • ‘interface’ (default: ‘"lo"’)
  130. The string interface to listen for incoming connections. This
  131. string may be an interface group, an IP address, or a domain
  132. name. These interfaces can usually be found by the command
  133. ‘ip link’.
  134. • ‘family’ (default: ‘#f’)
  135. Only listen on a specific address family. Valid strings are
  136. ‘"inet4"’ or ‘"inet6"’, which will only listen on IPv4 or IPv6
  137. respectfully. If ‘(family #f)’, then opensmtpd will listen on
  138. both IPv4 and IPv6.
  139. • ‘auth’ (default: ‘#f’) Support SMTPAUTH: clients may only
  140. start SMTP transactions after successful authentication. If
  141. ‘auth’ is ‘#t’, then users are authenticated against their own
  142. normal login credentials. Alternatively ‘auth’ may be a
  143. ‘mapping table’ that maps usernames to encrypted passwords.
  144. The password can be encrypted via the ‘smtpctl’ ‘encrypt’
  145. subcommand.
  146. • ‘auth-optional’ (default: ‘#f’) Support SMTPAUTH optionally:
  147. clients need not authenticate, but may do so. This allows the
  148. ‘<opensmtpd-interface>’ to both accept incoming mail from
  149. untrusted senders and permit outgoing mail from authenticated
  150. users. It can be used in situations where it is not possible
  151. to listen on a separate port (usually the submission port,
  152. 587) for users to authenticate. This option also accepts a
  153. ‘mapping table’ that maps usernames to encrypted passwords.
  154. • ‘filters’ (default: ‘#f’) A list of one or many
  155. ‘<opensmtpd-filter>’ or ‘<opensmtpd-filter-phase>’ records.
  156. The filters are applied sequentially. These records listen
  157. and filter on connections handled by this listener.
  158. • ‘hostname’ (default: ‘#f’) Change the default server name in
  159. the greeting banner instead of the default one.
  160. • ‘hostnames’ (default: ‘#f’) Override the server name for
  161. specific addresses. Use a ‘mapping table’ that maps string IP
  162. addresses to string hostnames. If the address on which the
  163. connection arrives appears in the mapping, the associated
  164. hostname is used.
  165. • ‘mask-src’ (default: ‘#f’) If ‘#t’, then omit the from part
  166. when prepending “Received” headers.
  167. • ‘disable-dsn’ (default: ‘#f’) When ‘#t’, then disable the DSN
  168. (Delivery Status Notification) extension.
  169. • ‘pki’ (default: ‘#f’) For secure connections, use an
  170. ‘<opensmtpd-pki>’ record to prove a mail server’s identity.
  171. • ‘port’ (default: ‘25’) Listen on the integer port instead of
  172. the default port of 25.
  173. • ‘proxy-v2’ (default: ‘#f’) If ‘#t’, then support the PROXYv2
  174. protocol, rewriting appropriately source address received from
  175. proxy.
  176. • ‘received-auth’ (default: ‘#f’) If ‘#t’, then in “Received”
  177. headers, report whether the session was authenticated and by
  178. which local user.
  179. • ‘senders’ (default: ‘#f’) Look up the authenticated user in
  180. the supplied ‘mapping table’ to find the email addresses that
  181. user is allowed to submit mail as.
  182. • ‘masquerade’ (default: ‘#f’) ‘masquerade’, is used in
  183. conjunction with ‘senders’. If ‘#t’, then the From header is
  184. rewritten to match the sender provided in the SMTP session.
  185. If ‘senders’ is ‘#false’, then ‘masquerade’ cannot be ‘#t’.
  186. • ‘secure-connection’ (default: ‘#f’) This is a string of one of
  187. these options:
  188. ‘"smtps"’ Support SMTPS, by default on port 465.
  189. ‘"tls"’ Support STARTTLS, by default on port 25.
  190. ‘"tls-require"’ Like ‘"tls"’, but force clients to
  191. establish a secure connection before being
  192. allowed to start an SMTP transaction.
  193. ‘"tls-require-verify"’ Like ‘"tls-require"’, but clients must
  194. also provide a valid certificate
  195. to establish an SMTP session.
  196. • ‘tag’ (default: ‘#f’) Clients connecting to the listener are
  197. tagged with the given string tag.
  198. • Data Type: opensmtpd-socket Data type representing the
  199. configuration of an ‘<opensmtpd-socket>’. Listen for incoming SMTP
  200. connections on the Unix domain socket ‘/var/run/smtpd.sock’. This
  201. is done by default, even if the record is absent.
  202. • ‘filters’ (default: ‘#f’) A list of one or many
  203. ‘<opensmtpd-filter>’ or ‘<opensmtpd-filter-phase>’ records.
  204. These filter incoming connections handled by this listener.
  205. • ‘mask-src’ (default: ‘#f’) If ‘#t’, then omit the from part
  206. when prepending “Received” headers.
  207. • ‘tag’ (default: ‘#f’) Clients connecting to the listener are
  208. tagged with the given string tag.
  209. • Data Type: opensmtpd-match This data type represents the
  210. configuration of an ‘<opensmtpd-match>’ record.
  211. If at least one mail envelope matches the options of one match
  212. record, receive the incoming message, put a copy into each matching
  213. envelope, and atomically save the envelopes to the mail spool for
  214. later processing by the respective ‘<opensmtpd-action>’ found in
  215. fieldname ‘action’. Here is an example ‘opensmtpd-match’ record.
  216. (opensmtpd-match
  217. (action (opensmtpd-local-delivery
  218. (name "receive")
  219. (method (opensmtpd-maildir
  220. (pathname "/home/%{rcpt.user}/Maildir")
  221. (junk #t)))
  222. (virtual (opensmtpd-table
  223. (name "virt")
  224. (data '(("carmen" . "carmen@gnu.org")))))))
  225. (options (list (opensmtpd-option
  226. (option "from any"))
  227. (opensmtpd-option
  228. (option "for domain")
  229. (data (opensmtpd-table
  230. (name "domain-table")
  231. (data (list "gnu.org" "fsf.org"))))))))
  232. • ‘action’ (default: ‘#f’)
  233. If mail matches this match configuration, then do this action.
  234. Valid values include ‘<opensmtpd-local-delivery>’ or
  235. ‘<opensmtpd-relay>’.
  236. • ‘options’ (default: ‘#f’) The fieldname ‘option’ is a list of
  237. unique ‘<opensmtpd-option>’ records.
  238. There are some mutually exclusive options: there can be only
  239. one “for” and only one “from” option.
  240. for from
  241. -------------------------------------------------------------
  242. only use one of the only use one of the following:
  243. following:
  244. ‘"for any"’ ‘"from any"’
  245. ‘"for local"’ ‘"from auth"’
  246. ‘"for domain"’ ‘"from local"’
  247. ‘"for rcpt-to"’ ‘"from mail-from"’
  248. ‘"from socket"’
  249. ‘"from src"’
  250. Additionally, some options require additional data via
  251. ‘<opensmtpd-option>’’s fieldname ‘data’. The following list
  252. will explain the below syntax.
  253. • ‘"for any"’ This option only requires fieldname ‘option’
  254. to have the string ‘"for any"’:
  255. (opensmtpd-option
  256. (option "for any"))
  257. • ‘"tag"’ _tag_ This option only requires fieldname
  258. ‘option’ to have the string ‘"tag"’ with a string in
  259. fieldname ‘data’:
  260. (opensmtpd-option
  261. (option "tag")
  262. (data "this-tag"))
  263. • ‘"for rcpt"’ _domain_ | <list table> This option requires
  264. fieldname ‘data’ to have a string domain or ‘list table’:
  265. (opensmtpd-option
  266. (option "for rcpt")
  267. (data "gnu.org"))
  268. OR
  269. (opensmtpd-option
  270. (option "for rcpt")
  271. (data (list "gnu.org" "fsf.org")))
  272. The following matching options are supported and can all be
  273. negated (via not #t). The options that support a table
  274. (anything surrounded with ’<’ and ’>’ eg: <table>), also
  275. support specifying regex via (regex #t).
  276. • ‘"for any"’ Specify that session may address any
  277. destination.
  278. • ‘"for local"’ Specify that session may address any local
  279. domain. This is the default, and may be omitted.
  280. • ‘"for domain"’ _domain_ | <domain> Specify that session
  281. may address the string _domain_ or ‘list table’ <domain>.
  282. • ‘"for rcpt-to"’ _recipient_ | <recipient> Specify that
  283. session may address the string _recipient_ or list table
  284. <recipient>.
  285. • ‘"from any"’ Specify that session may originate from any
  286. source.
  287. • ‘"from auth"’ Specify that session may originate from any
  288. authenticated user, no matter the source IP address.
  289. • ‘"from auth"’ _user_ | <user> Specify that the session
  290. may originate from authenticated _user_ or ‘list table’
  291. <user>, no matter the source IP address.
  292. • ‘"from local"’ Specify that session may only originate
  293. from a local IP address, or from the local enqueuer.
  294. This is the default, and may be omitted.
  295. • ‘"from mail-from"’ _sender_ | <sender> Specify that
  296. session may originate from _sender_ or ‘list table’
  297. <sender>, no matter the source IP address.
  298. • ‘"from rdns"’ Specify that session may only originate
  299. from an IP address that resolves to a reverse DNS.
  300. • ‘"from rdns"’ _hostname_ | <hostname> Specify that
  301. session may only originate from an IP address that
  302. resolves to a reverse DNS matching string _hostname_ or
  303. ‘list table’ <hostname>.
  304. • ‘"from socket"’ Specify that session may only originate
  305. from the local enqueuer.
  306. • ‘"from src"’ _address_ | <address> Specify that session
  307. may only originate from string _address_ or ‘list table’
  308. <address> which can be a specific address or a subnet
  309. expressed in CIDR-notation.
  310. • ‘"auth"’ Matches transactions which have been
  311. authenticated.
  312. • ‘"auth"’ _username_ | <username> Matches transactions
  313. which have been authenticated for string _user_ or ‘list
  314. table’ <username>.
  315. • ‘"helo"’ _helo-name_ | <helo-name> Specify that session’s
  316. HELO / EHLO should match the string _helo-name_ or ‘list
  317. table’ <helo-name>.
  318. • ‘"mail-from"’ _sender_ | <sender> Specify that
  319. transactions’s MAIL FROM should match the string _sender_
  320. or ‘list table’ <sender>.
  321. • ‘"rcpt-to"’ _recipient_ | <recipient> Specify that
  322. transaction’s RCPT TO should match the string _recipient_
  323. or ‘list table’ <recipient>.
  324. • ‘"tag"’ _tag_ Matches transactions tagged with the given
  325. tag.
  326. • ‘"tls"’ Specify that transaction should take place in a
  327. TLS channel.
  328. • Data Type: opensmtpd-local-delivery This data type represents the
  329. configuration of an ‘<opensmtpd-local-delivery>’ record.
  330. • ‘name’ (default: ‘#f’) ‘name’ is the string name of the relay
  331. action.
  332. • ‘method’ (default: ‘"mbox"’) The email delivery option. Valid
  333. options are:
  334. • ‘"mbox"’ Deliver the message to the user’s mbox with
  335. mail.local(8).
  336. • ‘"expand-only"’ Only accept the message if a delivery
  337. method was specified in an aliases or .forward file.
  338. • ‘"forward-only"’ Only accept the message if the recipient
  339. results in a remote address after the processing of
  340. aliases or forward file.
  341. • ‘<opensmtpd-lmtp>’ Deliver the message to an LMTP server
  342. at ‘<opensmtpd-lmtp>’’s fieldname ‘destination’. The
  343. location may be expressed as string host:port or as a
  344. UNIX socket. Optionally, ‘<opensmtpd-lmtp>’’s fieldname
  345. ‘rcpt-to’ might be specified to use the recipient email
  346. address (after expansion) instead of the local user in
  347. the LMTP session as RCPT TO.
  348. • ‘<opensmtpd-maildir>’ Deliver the message to the maildir
  349. in ‘<opensmtpd-maildir>’’s fieldname ‘pathname’ if
  350. specified, or by default to ‘"~/Maildir"’.
  351. The pathname may contain format specifiers that are
  352. expanded before use (see the below section about Format
  353. Specifiers).
  354. If ‘<opensmtpd-maildir>’’s record fieldname ‘junk’ is
  355. ‘#t’, then message will be moved to the ‘Junk’ folder if
  356. it contains a positive ‘X-Spam’ header. This folder will
  357. be created under fieldname ‘pathname’ if it does not yet
  358. exist.
  359. • ‘<opensmtpd-mda>’ Delegate the delivery to the
  360. ‘<opensmtpd-mda>’’s fieldname ‘command’ (type string)
  361. that receives the message on its standard input.
  362. The ‘command’ may contain format specifiers that are
  363. expanded before use (see Format Specifiers).
  364. • ‘alias’ (default: ‘#f’) Use the ‘mapping table’ for aliases
  365. expansion.
  366. • ‘ttl’ (default: ‘#f’) ‘ttl’ is a string specify how long a
  367. message may remain in the queue. It’s format is ‘n{s|m|h|d}’.
  368. eg: ‘"4m"’ is four minutes.
  369. • ‘user’ (default: ‘#f’ ) ‘user’ is the string username for
  370. performing the delivery, to be looked up with getpwnam(3).
  371. This is used for virtual hosting where a single username is in
  372. charge of handling delivery for all virtual users.
  373. This option is not usable with the mbox delivery method.
  374. • ‘userbase’ (default: ‘#f’) ‘userbase’ is an
  375. ‘<opensmtpd-table>’ record for mapping user lookups instead of
  376. the getpwnam(3) function.
  377. The fieldnames ‘user’ and ‘userbase’ are mutually exclusive.
  378. • ‘virtual’ (default: ‘#f’) ‘virtual’ is an ‘<opensmtpd-table>’
  379. record is used for virtual expansion.
  380. • Data Type: opensmtpd-relay This data type represents the
  381. configuration of an ‘<opensmtpd-relay>’ record.
  382. • ‘name’ (default: ‘#f’) ‘name’ is the string name of the relay
  383. action.
  384. • ‘backup’ (default: ‘#f’) When ‘#t’, operate as a backup mail
  385. exchanger delivering messages to any mail exchanger with
  386. higher priority.
  387. • ‘backup-mx’ (default: ‘#f’) Operate as a backup mail exchanger
  388. delivering messages to any mail exchanger with higher priority
  389. than mail exchanger identified as string name.
  390. • ‘helo’ (default: ‘#f’) Advertise string heloname as the
  391. hostname to other mail exchangers during the HELO phase.
  392. • ‘helo-src’ (default: ‘#f’ ) Use the mapping
  393. ‘<opensmtpd-table>’ to look up a hostname matching the source
  394. address, to advertise during the HELO phase.
  395. • ‘domain’ (default: ‘#f’) Do not perform MX lookups but look up
  396. destination domain in an ‘<opensmtpd-table>’ and use matching
  397. relay url as relay host.
  398. • ‘host’ (default: ‘#f’) Do not perform MX lookups but relay
  399. messages to the relay host described by the string relay-url.
  400. The format for relay-url is ‘[proto://[label@]]host[:port]’.
  401. The following protocols are available:
  402. ‘smtp’ Normal SMTP session with opportunistic STARTTLS (the default).
  403. ‘smtp+tls’ Normal SMTP session with mandatory STARTTLS.
  404. ‘smtp+notls’ Plain text SMTP session without TLS.
  405. ‘lmtp’ LMTP session. port is required.
  406. ‘smtps’ SMTP session with forced TLS on connection, default port is
  407. 465.
  408. Unless noted, port defaults to 25.
  409. The label corresponds to an entry in a credentials table, as
  410. documented in ‘man table’. It is used with the ‘"smtp+tls"’
  411. and ‘"smtps"’ protocols for authentication. Server
  412. certificates for those protocols are verified by default.
  413. • ‘pki’ (default: ‘#f’) For secure connections, use the
  414. certificate associated with ‘<opensmtpd-pki>’ (declared in a
  415. pki directive) to prove the client’s identity to the remote
  416. mail server.
  417. • ‘srs’ (default: ‘#f’) If ‘#t’, then when relaying a mail
  418. resulting from a forward, use the Sender Rewriting Scheme to
  419. rewrite sender address.
  420. • ‘tls’ (default: ‘#f’) boolean or string “no-verify” When ‘#t’,
  421. Require TLS to be used when relaying, using mandatory STARTTLS
  422. by default. When used with a smarthost, the protocol must not
  423. be ‘"smtp+notls://"’. When string ‘"no-verify"’, then do not
  424. require a valid certificate.
  425. • ‘auth’ (default: ‘#f’) ‘<opensmtpd-table>’ Use the alist
  426. ‘<opensmtpd-table>’ for connecting to relay-url using
  427. credentials. This option is usable only with fieldname ‘host’
  428. option.
  429. • ‘mail-from’ (default: ‘#f’) string Use the string mailaddress
  430. as MAIL FROM address within the SMTP transaction.
  431. • ‘src’ (default: ‘#f’) string | ‘<opensmtpd-table>’ Use the
  432. string or ‘<opensmtpd-table>’ sourceaddr for the source IP
  433. address, which is useful on machines with multiple interfaces.
  434. If the list contains more than one address, all of them are
  435. used in such a way that traffic is routed as efficiently as
  436. possible.
  437. • Data Type: opensmtpd-filter This data type represents the
  438. configuration of an ‘<opensmtpd-filter>’. This is the filter
  439. record one should use if they want to use an external package to
  440. filter email eg: rspamd or spamassassin.
  441. • ‘name’ (default: ‘#f’) The string name of the filter.
  442. • ‘proc’ (default: ‘#f’) The string command or process name. If
  443. ‘proc-exec’ is ‘#t’, ‘proc’ is treated as a command to
  444. execute. Otherwise, it is a process name.
  445. • ‘proc-exec’ (default: ‘#f’) If ‘#t’, then execute the command
  446. in ‘proc’.
  447. • Data Type: opensmtpd-filter-phase This data type represents the
  448. configuration of an ‘<opensmtpd-filter-phase>’.
  449. In a regular workflow, ‘smtpd(8)’ may accept or reject a message
  450. based only on the content of envelopes. Its decisions are about
  451. the handling of the message, not about the handling of an active
  452. session.
  453. Filtering extends the decision making process by allowing
  454. ‘smtpd(8)’ to stop at each phase of an SMTP session, check that
  455. options are met, then decide if a session is allowed to move
  456. forward.
  457. With filtering via an ‘<opensmtpd-filter-phase>’ record, a session
  458. may be interrupted at any phase before an envelope is complete. A
  459. message may also be rejected after being submitted, regardless of
  460. whether the envelope was accepted or not.
  461. • ‘name’ (default: ‘#f’)
  462. The string name of the filter phase.
  463. • ‘phase-name’ (default: ‘#f’) The string name of the phase.
  464. Valid values are:
  465. ‘"connect"’ upon connection, before a banner is displayed
  466. ‘"helo"’ after HELO command is submitted
  467. ‘"ehlo"’ after EHLO command is submitted
  468. ‘"mail-from"’ after MAIL FROM command is submitted
  469. ‘"rcpt-to"’ after RCPT TO command is submitted
  470. ‘"data"’ after DATA command is submitted
  471. ‘"commit"’ after message is fully is submitted
  472. • ‘options’ (default ‘#f’) A list of unique ‘<opensmtpd-option>’
  473. records.
  474. At each phase, various options, specified by a list of
  475. ‘<opensmtpd-option>’, may be checked. The
  476. ‘<opensmtpd-option>’’s fieldname ‘option’ values of:
  477. ‘"fcrdns"’, ‘"rdns"’, and ‘"src"’ data are available in all
  478. phases, but other data must have been already submitted before
  479. they are available. Options with a ‘<table>’ next to them
  480. require the ‘<opensmtpd-option>’’s fieldname ‘data’ to be an
  481. ‘<opensmtpd-table>’. There are the available options:
  482. ‘"fcrdns"’ forward-confirmed reverse DNS is
  483. valid
  484. ‘"rdns"’ session has a reverse DNS
  485. ‘"rdns"’ <table> session has a reverse DNS in table
  486. ‘"src"’ <table> source address is in table
  487. ‘"helo"’ <table> helo name is in table
  488. ‘"auth"’ session is authenticated
  489. ‘"auth"’ <table> session username is in table
  490. ‘"mail-from"’ <table> sender address is in table
  491. ‘"rcpt-to"’ <table> recipient address is in table
  492. These conditions may all be negated by setting
  493. ‘(opensmtpd-option (bool #f))’.
  494. Any conditions that require a table may indicate that tables
  495. include regexs setting ‘(opensmtpd-option (regex #t))’.
  496. • ‘decision’ A string decision to be taken. Some decisions
  497. require an ‘message’ or ‘value’. The value and message may be
  498. put in the ‘<opensmtpd-option>’’s fieldname ‘data’. Valid
  499. strings are:
  500. ‘"bypass"’ the session or transaction bypasses
  501. filters
  502. ‘"disconnect"’ message the session is disconnected with message
  503. ‘"junk"’ the session or transaction is junked,
  504. i.e., an ‘X-Spam: yes’ header is added to
  505. any messages
  506. ‘"reject"’ message the command is rejected with message
  507. ‘"rewrite"’ value the command parameter is rewritten with
  508. value
  509. Decisions that involve a message require that the message be
  510. RFC valid, meaning that they should either start with a 4xx or
  511. 5xx status code. Descisions can be taken at any phase, though
  512. junking can only happen before a message is committed.
  513. • ‘message’ (default ‘#f’) A string message beginning with a 4xx
  514. or 5xx status code.
  515. • ‘value’ (default: ‘#f’) A number value. ‘value’ and ‘message’
  516. are mutually exclusive.
  517. • Data Type: opensmtpd-option This data type represents the
  518. configuration of an ‘<opensmtpd-option>’, which is used by
  519. ‘<opensmtpd-filter-phase>’ and ‘<opensmtpd-match>’ to match various
  520. options for email.
  521. • ‘option’ (default ‘#f’) string
  522. A string option to be taken. Some options require the
  523. fieldname ‘data’ to have a string or an ‘<opensmtpd-table>’.
  524. When the option record is used inside of an
  525. ‘<opensmtpd-filter-phase>’, then valid strings for fieldname
  526. ‘option’ are:
  527. • ‘"fcrdns"’
  528. • ‘"rdns"’
  529. • ‘"src"’
  530. • ‘"helo"’
  531. • ‘"auth"’
  532. • ‘"mail-from"’
  533. • ‘"rcpt-to"’
  534. When ‘<opensmtpd-option>’ is used inside of an
  535. ‘<opensmtpd-match>’, then valid strings for fieldname ‘option’
  536. are:
  537. • ‘"for"’
  538. • ‘"for any"’
  539. • ‘"for local"’
  540. • ‘"for domain"’
  541. • ‘"for rcpt-to"’
  542. • ‘"from any"’
  543. • ‘"from auth"’
  544. • ‘"from local"’
  545. • ‘"from mail-from"’
  546. • ‘"from rdns"’
  547. • ‘"from socket"’
  548. • ‘"from src"’
  549. • ‘"auth"’
  550. • ‘"helo"’
  551. • ‘"mail-from"’
  552. • ‘"rcpt-to"’
  553. • ‘"tag"’
  554. • ‘"tls"’
  555. • ‘data’ (default ‘#f’) string | ‘<opensmtpd-table>’ Some
  556. options require a string or ‘<opensmtpd-table>’ to be present.
  557. One would specify that table here.
  558. • ‘regex’ (default: ‘#f’) boolean Any options using a table may
  559. indicate that tables hold regular expressions by setting this
  560. option to ‘#t’.
  561. • ‘bool’ (default: ‘#t’) boolean When ‘(bool #f)’, this option
  562. record is negated.
  563. • Data Type: opensmtpd-table This data type represents the
  564. configuration of an ‘<opensmtpd-table>’.
  565. • ‘name’ (default ‘#f’) ‘name’ is the name of the
  566. ‘<opensmtpd-table>’ record.
  567. • ‘data’ (default: ‘#f’) string | list | alist | nested-list
  568. ‘data’ expects a string, a list of strings, an alist of
  569. strings, or a nested list of strings. eg:
  570. • string
  571. (data "dev@gnu.org")
  572. A table of this type is called a ‘string table’.
  573. • list
  574. (data (list ("gnu.org" "fsf.org")))
  575. A table of this type is called a ‘list table’.
  576. • alist
  577. (data '(("james" . "$encryptedPassword")
  578. ("jennifer" . "$encryptedPassword2)))
  579. A table of this type is called a ‘mapping table’.
  580. • nested-list
  581. (data '(("user1" "root@gnu.org" "admin@gnu.org")
  582. ("user2" "james@guix.gnu.org" "sarah@fsf.org")))
  583. A table of this type is also called a ‘mapping table’.
  584. • Data Type: opensmtpd-pki This data type represents the
  585. configuration of an ‘<opensmtpd-pki>’.
  586. • ‘domain’ (default ‘#f’) ‘domain’ is the string name of the
  587. ‘<opensmtpd-pki>’ record.
  588. • ‘cert’ (default: ‘#f’) ‘cert’ (default: ‘#f’)
  589. ‘cert’ is the string certificate filename to use for this pki.
  590. • ‘key’ (default: ‘#f’) ‘key’ is the string certificate falename
  591. to use for this pki.
  592. • ‘dhe’ (default: ‘"none"’) Specify the DHE string parameter to
  593. use for DHE cipher suites with host pkiname. Valid parameter
  594. values are ‘"none"’, ‘"legacy"’, or ‘"auto"’. For ‘"legacy"’,
  595. a fixed key length of 1024 bits is used, whereas for ‘"auto"’,
  596. the key length is determined automatically. The default is
  597. ‘"none"’, which disables DHE cipher suites.
  598. • Data Type: opensmtpd-maildir
  599. • ‘pathname’ (default: ‘"~/Maildir"’) Deliver the message to the
  600. maildir if pathname if specified, or by default to
  601. ‘"~/Maildir"’.
  602. The pathname may contain format specifiers that are expanded
  603. before use (see FORMAT SPECIFIERS).
  604. • ‘junk’ (default: ‘#f’) If the junk argument is ‘#t’, then the
  605. message will be moved to the ‘‘Junk’’ folder if it contains a
  606. positive ‘‘X-Spam’’ header. This folder will be created under
  607. pathname if it does not yet exist.
  608. • Data Type: opensmtpd-mda This record lets you delegate the delivery
  609. to a command that receives the message on its standard input.
  610. • ‘name’ The string name for this MDA command.
  611. • ‘command’ The command to that delivers the mail.
  612. The command may contain format specifiers that are expanded
  613. before use (see FORMAT SPECIFIERS).
  614. • Data Type: opensmtpd-queue
  615. • ‘compression’ (default ‘#f’) Store queue files in a compressed
  616. format. This may be useful to save disk space.
  617. • ‘encryption’ (default ‘#f’) Encrypt queue files with
  618. EVP_aes_256_gcm(3). If no key is specified, it is read with
  619. getpass(3). If the string stdin or a single dash (‘-’) is
  620. given instead of a key, the key is read from the standard
  621. input.
  622. • ‘ttl-delay’ (default ‘#f’) Set the default expiration time for
  623. temporarily undeliverable messages, given as a positive
  624. decimal integer followed by a unit s, m, h, or d. The default
  625. is four days (‘"4d"’).
  626. • Data Type: opensmtpd-smtp Data type representing an
  627. ‘<opensmtpd-smtp>’ record.
  628. • ‘ciphers’ (default: ‘#f’) Set the control string for
  629. SSL_CTX_set_cipher_list(3). The default is
  630. “HIGH:!aNULL:!MD5”.
  631. • ‘limit-max-mails’ (default: ‘100’) Limit the number of
  632. messages to count for each sessio
  633. • ‘limit-max-rcpt’ (default: ‘1000’) Limit the number of
  634. recipients to count for each transaction.
  635. • ‘max-message-size’ (default: ‘35M’) Reject messages larger
  636. than size, given as a positive number of bytes or as a string
  637. to be parsed with scan_scaled(3).
  638. • ‘sub-addr-delim character’ (default: ‘+’) When resolving the
  639. local part of a local email address, ignore the ASCII
  640. character and all characters following it. This is helpful
  641. for email filters. ‘"admin+bills@gnu.org"’ is the same email
  642. address as ‘"admin@gnu.org"’. BUT an email filter can filter
  643. emails addressed to first email address into a ’Bills’ email
  644. folder.
  645. • Data Type: opensmtpd-srs Use this record to set up the Sender
  646. Rewriting Scheme (SRS).
  647. • ‘key’ (default: ‘#f’) Set the secret key to use for SRS, the
  648. Sender Rewriting Scheme.
  649. • ‘backup-key’ (default: ‘#f’) Set a backup secret key to use as
  650. a fallback for SRS. This can be used to implement SRS key
  651. rotation.
  652. • ‘ttl-delay’ (default: ‘"4d"’) Set the time-to-live delay for
  653. SRS envelopes. After this delay, a bounce reply to the SRS
  654. address will be discarded to limit risks of forged addresses.
  655. • Format Specifiers Some configuration records support expansion of
  656. their parameters at runtime. Such records (for example
  657. ‘<opensmtpd-maildir>’, ‘<opensmtpd-mda>’) may use format specifiers
  658. which are expanded before delivery or relaying. The following
  659. formats are currently supported:
  660. ‘%{sender}’ sender email address, may be empty string
  661. ‘%{sender.user}’ user part of the sender email address, may be empty
  662. ‘%{sender.domain}’ domain part of the sender email address, may be empty
  663. ‘%{rcpt}’ recipient email address
  664. ‘%{rcpt.user}’ user part of the recipient email address
  665. ‘%{rcpt.domain}’ domain part of the recipient email address
  666. ‘%{dest}’ recipient email address after expansion
  667. ‘%{dest.user}’ user part after expansion
  668. ‘%{dest.domain}’ domain part after expansion
  669. ‘%{user.username}’ local user
  670. ‘%{user.directory}’ home directory of the local user
  671. ‘%{mbox.from}’ name used in mbox From separator lines
  672. ‘%{mda}’ mda command, only available for mda wrappers
  673. Expansion formats also support partial expansion using the optional
  674. bracket notations with substring offset. For example, with
  675. recipient domain ‘“example.org”’:
  676. ‘%{rcpt.domain[0]}’ expands to “e”
  677. ‘%{rcpt.domain[1]}’ expands to “x”
  678. ‘%{rcpt.domain[8:]}’ expands to “org”
  679. ‘%{rcpt.domain[-3:]}’ expands to “org”
  680. ‘%{rcpt.domain[0:6]}’ expands to “example”
  681. ‘%{rcpt.domain[0:-4]}’ expands to “example”
  682. In addition, modifiers may be applied to the token. For example,
  683. with recipient ‘“User+Tag@Example.org”’:
  684. ‘%{rcpt:lowercase}’ expands to “user+tag@example.org”
  685. ‘%{rcpt:uppercase}’ expands to “USER+TAG@EXAMPLE.ORG”
  686. ‘%{rcpt:strip}’ expands to “User@Example.org”
  687. ‘%{rcpt:lowercasestrip}’ expands to “user@example.org”
  688. For security concerns, expanded values are sanitized and
  689. potentially dangerous characters are replaced with ‘:’. In
  690. situations where they are desirable, the “raw” modifier may be
  691. applied. For example, with recipient ‘“user+t?g@example.org”’:
  692. ‘%{rcpt}’ expands to “user+t:g@example.org”
  693. ‘%{rcpt:raw}’ expands to “user+t?g@example.org”