msmtp.1 (42510B)
- .\" -*-nroff-*-
- .\"
- .\" Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
- .\" 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022
- .\" Martin Lambers
- .\" Copyright (C) 2011
- .\" Scott Shumate
- .\"
- .\" Permission is granted to copy, distribute and/or modify this document
- .\" under the terms of the GNU Free Documentation License, Version 1.2 or
- .\" any later version published by the Free Software Foundation; with no
- .\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- .TH MSMTP 1 2022-06
- .SH NAME
- msmtp \- An SMTP client
- .SH SYNOPSIS
- .IP "Sendmail mode (default):"
- .B msmtp
- [option...] [\-\-] recipient...
- .br
- .B msmtp
- [option...] \-t [\-\-] [recipient...]
- .IP "Configuration mode:"
- .B msmtp
- \-\-configure <mailaddress>
- .IP "Server information mode:"
- .B msmtp
- [option...] \-\-serverinfo
- .IP "Remote Message Queue Starting mode:"
- .B msmtp
- [option...] \-\-rmqs=\fIhost\fP|\fI@domain\fP|\fI#queue\fP
- .SH DESCRIPTION
- In the default sendmail mode, msmtp reads a mail from standard input and sends
- it to an SMTP server for delivery.
- .br
- In server information mode, msmtp prints information about an SMTP server.
- .br
- In Remote Message Queue Starting mode, msmtp sends a Remote Message Queue
- Starting request for a host, domain, or queue to an SMTP server.
- .SH EXIT STATUS
- The standard sendmail exit status codes are used, as defined in sysexits.h.
- .SH OPTIONS
- Options override configuration file settings.
- .br
- They are compatible with sendmail where appropriate.
- .IP "\fBGeneral options\fP"
- .RS
- .IP "\-\-version"
- Print version information, including information about the libraries used.
- .IP "\-\-help"
- Print help.
- .IP "\-P, \-\-pretend"
- Print the configuration settings that would be used, but do not take further
- action. An asterisk (`*') will be printed instead of your password.
- .IP "\-v, \-d, \-\-debug"
- Print lots of debugging information, including the whole conversation with the
- SMTP server. Be careful with this option: the (potentially dangerous) output
- will not be sanitized, and your password may get printed in an easily decodable
- format!
- .RE
- .IP "\fBChanging the mode of operation\fP"
- .RS
- .IP "\-\-configure=\fImailaddress\fP"
- Generate a configuration for the given mail address and print it. This can be
- modified or copied unchanged to the configuration file.
- Note that this only works for mail domains that publish appropriate SRV records;
- see RFC 8314.
- .IP "\-S, \-\-serverinfo"
- Print information about the SMTP server and exit. This includes information
- about supported features (mail size limit, authentication, TLS, DSN, ...) and
- about the TLS certificate (if TLS is active).
- .IP "\-\-rmqs=(\fIhost\fP|\fI@domain\fP|\fI#queue\fP)"
- Send a Remote Message Queue Starting request for the given host, domain, or
- queue to the SMTP server and exit.
- .RE
- .IP "\fBConfiguration options\fP"
- .RS
- .IP "\-C, \-\-file=\fIfilename\fP"
- Use the given file instead of ~/.msmtprc or $XDG_CONFIG_HOME/msmtp/config as
- the user configuration file.
- .IP "\-a, \-\-account=\fIaccount_name\fP"
- Use the given account instead of the account named "default". The settings of
- this account may be changed with command line options. This option cannot be
- used together with the \fB\-\-host\fP option.
- .IP "\-\-host=\fIhostname\fP"
- Use this SMTP server with settings from the command line; do not use any
- configuration file data. This option cannot be used together with the
- \fB\-\-account\fP option.
- .IP "\-\-port=\fInumber\fP"
- Set the port number to connect to. See the \fBport\fP command.
- .IP "\-\-source\-ip=[\fIIP\fP]"
- Set or unset an IP address to bind the socket to. See the \fBsource_ip\fP command.
- .IP "\-\-proxy\-host=[\fIIP\fP|\fIhostname\fP]"
- Set or unset a SOCKS proxy to use. See the \fBproxy_host\fP command.
- .IP "\-\-proxy\-port=[\fInumber\fP]"
- Set or unset a port number for the proxy host. See the \fBproxy_port\fP command.
- .IP "\-\-socket=[\fIsocketname\fP]"
- Set or unset a local unix domain socket name to connect to. See the \fBsocket\fP command.
- .IP "\-\-timeout=(\fIoff\fP|\fIseconds\fP)"
- Set or unset a network timeout, in seconds. See the \fBtimeout\fP command.
- .IP "\-\-protocol=(\fIsmtp\fP|\fIlmtp\fP)
- Set the protocol. See the \fBprotocol\fP command.
- .IP "\-\-domain=[\fIstring\fP]"
- Set the argument of the SMTP EHLO (or LMTP LHLO) command. See the \fBdomain\fP
- command.
- .IP "\-\-auth[=(\fIon\fP|\fIoff\fP|\fImethod\fP)]"
- Enable or disable authentication and optionally choose the method.
- See the \fBauth\fP command.
- .IP "\-\-user=\fI[username]\fP"
- Set or unset the user name for authentication. See the \fBuser\fP command.
- .IP "\-\-passwordeval=[\fIcmd\fP]"
- Evaluate password for authentication. See the \fBpasswordeval\fP command.
- .IP "\-\-tls[=(\fIon\fP|\fIoff\fP)]"
- Enable or disable TLS/SSL. See the \fBtls\fP command.
- .IP "\-\-tls\-starttls[=(\fIon\fP|\fIoff\fP)]"
- Enable or disable STARTTLS for TLS. See the \fBtls_starttls\fP command.
- .IP "\-\-tls\-trust\-file=[\fIfile\fP]"
- Set or unset a trust file for TLS. See the \fBtls_trust_file\fP command.
- .IP "\-\-tls\-crl\-file=[\fIfile\fP]"
- Deprecated. Set or unset a certificate revocation list (CRL) file for TLS. See the
- \fBtls_crl_file\fP command.
- .IP "\-\-tls\-fingerprint=[\fIfingerprint\fP]"
- Set or unset the fingerprint of a trusted TLS certificate. See the
- \fBtls_fingerprint\fP command.
- .IP "\-\-tls\-key\-file=[\fIfile\fP]"
- Set or unset a key file for TLS. See the \fBtls_key_file\fP command.
- .IP "\-\-tls\-cert\-file=[\fIfile\fP]"
- Set or unset a cert file for TLS. See the \fBtls_cert_file\fP command.
- .IP "\-\-tls\-certcheck[=(\fIon\fP|\fIoff\fP)]"
- Enable or disable server certificate checks for TLS. See the
- \fBtls_certcheck\fP command.
- .IP "\-\-tls\-priorities=[\fIpriorities\fP]"
- Set or unset TLS priorities. See the \fBtls_priorities\fP command.
- .IP "\-\-tls\-host\-override=[\fIhost\fP]"
- Set or unset override for TLS host verification. See the \fBtls_host_override\fP command.
- .IP "\-\-tls\-min\-dh\-prime\-bits=[\fIbits\fP]"
- Deprecated, use \-\-tls\-priorities instead.
- Set or unset minimum bit size of the Diffie-Hellman (DH) prime. See the
- \fBtls_min_dh_prime_bits\fP command.
- .RE
- .IP "\fBOptions specific to sendmail mode\fP"
- .RS
- .IP "\-f, \-\-from=\fIaddress\fP"
- Set the envelope-from address.
- .br
- If no account was chosen yet (with \fB\-\-account\fP or \fB\-\-host\fP), this
- option will choose the first account that has the given envelope-from address
- (set with the \fBfrom\fP command). If no such account is found, "default" is
- used.
- .br
- See the \fBfrom\fP and \fBallow_from_override\fP commands.
- .IP "\-N, \-\-dsn\-notify=(\fIoff\fP|\fIcond\fP)"
- Set or unset DSN notification conditions. See the \fBdsn_notify\fP command.
- .IP "\-R, \-\-dsn\-return=(\fIoff\fP|\fIret\fP)"
- Set or unset the DSN notification amount. See the \fBdsn_return\fP command.
- Note that \fIhdrs\fP is accepted as an alias for \fIheaders\fP to be
- compatible with sendmail.
- .IP "\-\-set\-from\-header[=(\fIauto\fP|\fIon\fP|\fIoff\fP)]"
- Set From header handling. See the \fBset_from_header\fP command.
- .IP "\-\-set\-date\-header[=(\fIauto\fP|\fIoff\fP)]"
- Set Date header handling. See the \fBset_date_header\fP command.
- .IP "\-\-set\-msgid\-header[=(\fIauto\fP|\fIoff\fP)]"
- Set Message-ID header handling. See the \fBset_msgid_header\fP command.
- .IP "\-\-remove\-bcc\-headers[=(\fIon\fP|\fIoff\fP)]"
- Enable or disable the removal of Bcc headers. See the \fBremove_bcc_headers\fP
- command.
- .IP "\-\-undisclosed\-recipients[=(\fIon\fP|\fIoff\fP)]"
- Enable or disable the replacement of To/Cc/Bcc with "To: undisclosed-recipients:;".
- See the \fBundisclosed_recipients\fP command.
- .IP "\-X, \-\-logfile=[\fIfile\fP]"
- Set or unset the log file. See the \fBlogfile\fP command.
- .IP "\-\-logfile\-time\-format=[\fIfmt\fP]"
- Set or unset the log file time format. See the \fBlogfile_time_format\fP command.
- .IP "\-\-syslog[=(\fIon\fP|\fIoff\fP|\fIfacility\fP)]"
- Enable or disable syslog logging. See the \fBsyslog\fP command.
- .IP "\-t, \-\-read\-recipients"
- Read recipient addresses from the To, Cc, and Bcc headers of the mail in
- addition to the recipients given on the command line.
- If any Resent- headers are present, then the addresses from any Resent-To,
- Resent-Cc, and Resent-Bcc headers in the first block of Resent- headers are
- used instead.
- .IP "\-\-read\-envelope\-from"
- Read the envelope from address from the From header of the mail.
- .IP "\-\-aliases=[\fIfile\fP]"
- Set or unset an aliases file. See the \fBaliases\fP command.
- .IP "\-F\fIname\fP"
- Msmtp adds a From header to mails that lack it, using the envelope from
- address. This option allows one to set a full name to be used in that header.
- .IP "\-\-auto\-from[=(\fIon\fP|\fIoff\fP)]"
- Obsolete. See the \fBauto_from\fP command.
- .IP "\-\-maildomain=[\fIdomain\fP]"
- Obsolete. See the \fBmaildomain\fP command.
- .IP "\-\-"
- This marks the end of options. All following arguments will be treated as
- recipient addresses, even if they start with a `\-'.
- .RE
- .PP
- The following options are accepted but ignored for sendmail compatibility:
- .br
- \-B\fItype\fP, \-bm, \-G, \-h\fIN\fP, \-i, \-L \fItag\fP, \-m,
- \-n, \-O \fIoption=value\fP, \-o\fIx\fP \fIvalue\fP
- .SH USAGE
- A suggestion for a suitable configuration file can be generated using the
- \-\-configure option.
- Normally, a system wide configuration file and/or a user configuration file
- contain information about which SMTP server to use and how to use it, but
- all settings can also be configured on the command line.
- .br
- The information about SMTP servers is organized in accounts. Each account
- describes one SMTP server: host name, authentication settings, TLS settings,
- and so on. Each configuration file can define multiple accounts.
- .PP
- The user can choose which account to use in one of three ways:
- .IP "\-\-account=\fIid\fP"
- Use the given account. Command line settings override configuration file
- settings.
- .IP "\-\-host=\fIhostname\fP
- Use only the settings from the command line; do not use any configuration file
- data.
- .IP "\-\-from=\fIaddress\fP or \-\-read\-envelope\-from"
- Choose the first account from the system or user configuration file that has
- a matching envelope-from address as specified by a \fBfrom\fP command. This
- works only when neither \fB\-\-account\fP nor \fB\-\-host\fP is used.
- .br
- Subadresses are supported. For example, the envelope from address
- \fIuser+detail@example.com\fP will match the account for \fIuser@example.com\fP.
- .br
- Furthermore, the envelope-from address of the account may be a wildcard pattern.
- See the \fBfrom\fP command.
- .PP
- If none of the above options is used (or if no account has a matching
- \fBfrom\fP command), then the account "default" is used.
- .PP
- Msmtp transmits mails unaltered to the SMTP server, with the following exceptions:
- .br
- - The Bcc header(s) will be removed. This behavior can be changed with the
- \fBremove_bcc_headers\fP command and \fB\-\-remove\-bcc\-headers\fP option.
- .br
- - A From header will be added if the mail does not have one. This can be changed
- with the \fBset_from_header\fP command and \fB\-\-set\-from\-header\fP option.
- The header will use the envelope from address and optionally a full name set
- with the \fB\-F\fP option.
- .br
- - A Date header will be added if the mail does not have one. This can be changed
- with the \fBset_date_header\fP command and \fB\-\-set\-date\-header\fP option.
- .br
- - A Message-ID header will be added if the mail does not have one. This can be changed
- with the \fBset_msg_header\fP command and \fB\-\-set\-msgid\-header\fP option.
- .br
- - When \fBundisclosed_recipients\fP is set, the original To, Cc, and Bcc headers
- are removed and replaced with "To: undisclosed-recipients:;".
- .PP
- Skip to the EXAMPLES section for a quick start.
- .SH CONFIGURATION FILES
- If it exists and is readable, a system wide configuration file
- SYSCONFDIR/msmtprc will be loaded, where SYSCONFDIR depends on your platform.
- Use \fB\-\-version\fP to find out which directory is used.
- .br
- If it exists and is readable, a user configuration file will be loaded
- (~/.msmtprc will be tried first followed by $XDG_CONFIG_HOME/msmtp/config by
- default, but see \fB\-\-version\fP). Accounts defined in the user configuration
- file override accounts from the system configuration file.
- .br
- Configuration data from either file can be changed by command line options.
- .PP
- A configuration file is a simple text file. Empty lines and comment lines
- (whose first non-blank character is `#') are ignored.
- .br
- Every other line must contain a command and may contain an argument to that
- command.
- .br
- The argument may be enclosed in double quotes ("), for example if its first or
- last character is a blank.
- .br
- If a file name starts with the tilde (~), this tilde will be replaced by $HOME.
- If a command accepts the argument \fIon\fP, it also accepts an empty argument
- and treats that as if it was \fIon\fP.
- .br
- Commands are organized in accounts. Each account starts with the \fBaccount\fP
- command and defines the settings for one SMTP account.
- .PP
- Skip to the EXAMPLES section for a quick start.
- .PP
- Commands are as follows:
- .IP "defaults"
- Set defaults. The following configuration commands will set default values for
- all following account definitions in the current configuration file.
- .IP "account \fIname\fP [:\fIaccount\fP[,...]]"
- Start a new account definition with the given name. The current default values
- are filled in.
- .br
- If a colon and a list of previously defined accounts is given after the account
- name, the new account, with the filled in default values, will inherit all
- settings from the accounts in the list.
- .IP "eval \fIcmd\fP"
- Replace the current configuration file line with the first line of the output
- (stdout) of the command \fIcmd\fP. This can be used to decrypt settings or to
- create them via scripts. For example, \fIeval echo host localhost\fP replaces
- the current line with \fIhost localhost\fP.
- .br
- The \fIcmd\fP command must not mess with standard input; if in doubt, append
- \fI< /dev/null\fP.
- .br
- Note that for passwords you can also use the \fBpasswordeval\fP command instead
- of \fIeval password cmd\fP. This has the advantage that the command is only
- evaluated if needed.
- .IP "host \fIhostname\fP"
- The SMTP server to send the mail to.
- The argument may be a host name or a network address.
- Every account definition must contain this command.
- .IP "port \fInumber\fP"
- The port that the SMTP server listens on.
- The default is 25 ("smtp"), unless TLS without STARTTLS is used, in which case
- it is 465 ("smtps").
- .IP "source_ip [\fIIP\fP]"
- Set a source IP address to bind the outgoing connection to. Useful only in
- special cases on multi-home systems. An empty argument disables this.
- .IP "proxy_host [\fIIP|hostname\fP]"
- Use a SOCKS proxy. All network traffic will go through this proxy host,
- including DNS queries, except for a DNS query that might be necessary to
- resolve the proxy host name itself (this can be avoided by using an IP address
- as proxy host name). An empty \fIhostname\fP argument disables proxy usage.
- The supported SOCKS protocol version is 5. If you want to use this with Tor,
- see also "Using msmtp with Tor" below.
- .IP "proxy_port [\fInumber\fP]"
- Set the port number for the proxy host. An empty \fInumber\fP argument resets
- this to the default port.
- .IP "socket \fIsocketname\fP"
- Set the file name of a unix domain socket to connect to. This overrides
- both \fBhost\fP/\fBport\fP and \fBproxy_host\fP/\fBproxy_port\fP.
- .IP "timeout (\fIoff\fP|\fIseconds\fP)"
- Set or unset a network timeout, in seconds. The argument \fIoff\fP means that no
- timeout will be set, which means that the operating system default will be used.
- .IP "protocol (\fIsmtp\fP|\fIlmtp\fP)"
- Set the protocol to use. Currently only SMTP and LMTP are supported. SMTP is
- the default. See the \fBport\fP command above for default ports.
- .IP "domain \fIargument\fP"
- Use this command to set the argument of the SMTP EHLO (or LMTP LHLO) command.
- The default is \fIlocalhost\fP, which is stupid but usually works. Try to
- change the default if mails get rejected due to anti-SPAM measures. Possible
- choices are the domain part of your mail address (provider.example for
- joe@provider.example) or the fully qualified domain name of your host (if
- available).
- .br
- The following substitution patterns are supported:
- .br
- %H will be replaced by $HOSTNAME, or if that fails by the host name of the system.
- .br
- %C will be replaced by the canonical name of %H.
- .br
- %M will be replaced by the contents of /etc/mailname (potentially a different
- directory is used depending on the build configuration; see the output of msmtp
- \-\-version and look for the location of the system configuration file).
- .IP "auth [(\fIon\fP|\fIoff\fP|\fImethod\fP)]"
- Enable or disable authentication and optionally choose a method to use. The
- argument \fIon\fP chooses a method automatically.
- .br
- Usually a user name and a password are used for authentication. The user name
- is specified in the configuration file with the \fBuser\fP command. There are five
- different methods to specify the password:
- .br
- 1. Add the password to the system key ring.
- Currently supported key rings are the Gnome key ring and the Mac OS X Keychain.
- For the Gnome key ring, use the command secret\-tool (part of Gnome's
- libsecret) to store passwords: secret\-tool store \-\-label=msmtp host
- mail.freemail.example service smtp user joe.smith.
- On Mac OS X, use the following command: security add\-internet\-password
- \-s mail.freemail.example \-r smtp \-a joe.smith \-w.
- In both examples, replace mail.freemail.example with the SMTP server name, and
- joe.smith with your user name.
- .br
- 2. Store the password in an encrypted files, and use \fBpasswordeval\fP
- to specify a command to decrypt that file, e.g. using GnuPG. See EXAMPLES.
- .br
- 3. Store the password in the configuration file using the \fBpassword\fP command.
- (Usually it is not considered a good idea to store passwords in cleartext files.
- If you do it anyway, you must make sure that the file can only be read by yourself.)
- .br
- 4. Store the password in ~/.netrc. This method is probably obsolete.
- .br
- 5. Type the password into the terminal when it is required.
- .br
- It is recommended to use method 1 or 2.
- .br
- Multiple authentication methods exist. Most servers support only some of them.
- Historically, sophisticated methods were developed to protect passwords from
- being sent unencrypted to the server, but nowadays everybody needs TLS anyway,
- so the simple methods suffice since the whole session is protected. A suitable
- authentication method is chosen automatically, and when TLS is disabled for
- some reason, only methods that avoid sending cleartext passwords are
- considered.
- .br
- The following user / password methods are supported: \fIplain\fP (a simple
- cleartext method, with base64 encoding, supported by almost all servers),
- \fIscram\-sha\-1\fP (a method that avoids cleartext passwords),
- \fIscram\-sha\-256\fP (same but with stronger hash),
- \fIcram\-md5\fP (an obsolete method that avoids cleartext passwords, but is not
- considered secure anymore),
- \fIdigest\-md5\fP (an overcomplicated
- obsolete method that avoids cleartext passwords, but is not considered secure
- anymore), \fIlogin\fP (a non-standard cleartext method similar to but worse
- than the plain method), \fIntlm\fP (an obscure non-standard method that is now
- considered broken; it sometimes requires a special domain parameter passed via
- \fBntlmdomain\fP).
- .br
- There are currently three authentication methods that are not based on user /
- password information and have to be chosen manually: \fIoauthbearer\fP or its
- predecessor \fIxoauth2\fP (an OAuth2
- token from the mail provider is used as the password.
- See the documentation of your mail provider for details on how to get this
- token. The \fBpasswordeval\fP command can be used to pass the regularly changing
- tokens into msmtp from a script or an environment variable),
- \fIexternal\fP (the
- authentication happens outside of the protocol, typically by sending a TLS
- client certificate, and the method merely confirms that this authentication
- succeeded), and \fIgssapi\fP (the Kerberos framework takes care of secure
- authentication, only a user name is required).
- .br
- It depends on the underlying authentication library and its version whether a
- particular method is supported or not. Use \fB\-\-version\fP to find out which
- methods are supported.
- .IP "user \fIlogin\fP"
- Set the user name for authentication. An empty argument unsets the user name.
- .IP "password \fIsecret\fP"
- Set the password for authentication. An empty argument unsets the password.
- Consider using the \fBpasswordeval\fP command or a key ring instead of this
- command, to avoid storing cleartext passwords in the configuration file.
- .IP "passwordeval [\fIcmd\fP]"
- Set the password for authentication to the output (stdout) of the command
- \fIcmd\fP.
- This can be used e.g. to decrypt password files on the fly or to query key
- rings, and thus to avoid storing cleartext passwords.
- .br
- The \fIcmd\fP command must not mess with standard input; if in doubt, append
- \fI< /dev/null\fP.
- .IP "ntlmdomain [\fIdomain\fP]"
- Set a domain for the \fBntlm\fP authentication method. This is obsolete.
- .IP "tls [(\fIon\fP|\fIoff\fP)]"
- Enable or disable TLS (also known as SSL) for secured connections.
- .br
- Transport Layer Security (TLS)
- "... provides communications privacy over the Internet. The protocol
- allows client/server applications to communicate in a way that is designed to
- prevent eavesdropping, tampering, or message forgery" (quote from RFC2246).
- .br
- A server can use TLS in one of two modes: via a STARTTLS command (the session
- starts with the normal protocol initialization, and TLS is then
- started using the protocol's STARTTLS command), or immediately (TLS is
- initialized before the normal protocol initialization; this requires a
- separate port). The first mode is the default, but you can switch to the
- second mode by disabling \fBtls_starttls\fP.
- .br
- When TLS is started, the server sends a certificate to identify itself. To
- verify the server identity, a client program is expected to check that the
- certificate is formally correct and that it was issued by a Certificate
- Authority (CA) that the user trusts. (There can also be certificate chains with
- intermediate CAs.)
- .br
- The list of trusted CAs is specified using the \fBtls_trust_file\fP command.
- The default value ist "system" and chooses the system-wide default, but you can
- also choose the trusted CAs yourself.
- .br
- A fundamental problem with this is that you need to trust CAs.
- Like any other organization, a CA can be incompetent, malicious, subverted by
- bad people, or forced by government agencies to compromise end users without
- telling them. All of these things happened and continue to happen worldwide.
- The idea to have central organizations that have to be trusted for your
- communication to be secure is fundamentally broken.
- .br
- Instead of putting trust in a CA, you can choose to trust only a single
- certificate for the server you want to connect to. For that purpose, specify
- the certificate fingerprint with \fBtls_fingerprint\fP. This makes sure that no
- man-in-the-middle can fake the identity of the server by presenting you a
- fraudulent certificate issued by some CA that happens to be in your trust list.
- However, you have to update the fingerprint whenever the server certificate
- changes, and you have to make sure that the change is legitimate each time,
- e.g. when the old certificate expired. This is inconvenient, but it's the price
- to pay.
- .br
- Information about a server certificate can be obtained with \fI\-\-serverinfo
- \-\-tls \-\-tls\-certcheck=off\fP. This includes the issuer CA of the certificate (so
- you can trust that CA via \fBtls_trust_file\fP), and the fingerprint of the
- certificate (so you can trust that particular certificate via
- \fBtls_fingerprint\fP).
- .br
- TLS also allows the server to verify the identity of the client. For this
- purpose, the client has to present a certificate issued by a CA that the server
- trusts. To present that certificate, the client also needs the matching key
- file. You can set the certificate and key files using \fBtls_cert_file\fP and
- \fBtls_key_file\fP. This mechanism can also be used to authenticate users, so
- that traditional user / password authentication is not necessary anymore. See the
- \fIexternal\fP mechanism in \fBauth\fP.
- .br
- You can also use client certificates stored on some external authentication
- device by specifying GnuTLS device URIs in \fBtls_cert_file\fP and
- \fBtls_key_file\fP. You can find the correct URIs using \fBp11tool
- \-\-list-privkeys \-\-login\fP (p11tool is bundled with GnuTLS). If your device
- requires a PIN to access the data, you can specify that using one of the
- password mechanisms (e.g. \fBpasswordeval\fP, \fBpassword\fP).
- .IP "tls_starttls [(\fIon\fP|\fIoff\fP)]"
- Choose the TLS variant: start TLS from within the session (\fIon\fP, default),
- or tunnel the session through TLS (\fIoff\fP).
- .IP "tls_trust_file \fIfile\fP"
- Activate server certificate verification using a list of trusted Certification
- Authorities (CAs). The default is the special value "system", which selects the
- system default. An empty argument disables trust in CAs.
- If you select a file, it must be in PEM format, and you should also use
- \fBtls_crl_file\fP.
- .IP "tls_crl_file [\fIfile\fP]"
- Deprecated. This sets a certificate revocation list (CRL) file for TLS, to check
- for revoked certificates (an empty argument, which is the default, disables this).
- Nowadays automatic OCSP checks replace CRL file checks.
- .IP "tls_fingerprint [\fIfingerprint\fP]"
- Set the fingerprint of a single certificate to accept for TLS. This certificate
- will be trusted regardless of its contents (this overrides \fBtls_trust_file\fP).
- The fingerprint should be of type SHA256, but can for backwards compatibility
- also be of type SHA1 or MD5 (please avoid this).
- The format should be 01:23:45:67:....
- Use \fI\-\-serverinfo \-\-tls \-\-tls\-certcheck=off \-\-tls\-fingerprint=\fP
- to get the server certificate fingerprint.
- .IP "tls_key_file \fIfile\fP"
- Send a client certificate to the server (use this together with
- \fBtls_cert_file}\fP).
- The file must contain the private key of a certificate in PEM format. An empty
- argument disables this feature.
- .IP "tls_cert_file \fIfile\fP"
- Send a client certificate to the server (use this together with
- \fBtls_key_file\fP).
- The file must contain a certificate in PEM format. An empty argument disables
- this feature.
- .IP "tls_certcheck [(\fIon\fP|\fIoff\fP)]"
- Enable or disable checks of the server certificate. They are enabled by default.
- Disabling them will override \fBtls_trust_file\fP and \fBtls_fingerprint\fP.
- WARNING: When the checks are disabled, TLS sessions will not be secure!
- .IP "tls_priorities [\fIpriorities\fP]"
- Set priorities for TLS session parameters. The default is set by the TLS library and
- can be selected by using an empty argument to this command. The interpretation of the
- \fIpriorities\fP string depends on the TLS library. Use \fI\-\-version\fP to find out
- which TLS library you use.
- .br
- For GnuTLS, see the section on Priority Strings in the manual.
- .br
- For libtls, the \fIpriorites\fP string is a space-separated list of parameter strings
- prefixed with either PROTOCOLS=, CIPHERS=, or ECDHECURVES=. These parameter strings
- will be passed to the functions \fItls_config_parse_protocols\fP, \fItls_config_set_ciphers\fP,
- and \fItls_config_set_ecdhecurves\fP. Unrecognized parts of the \fIpriorities\fP string
- will be ignored. Example: "PROTOCOLS=TLSv1.3 CIPHERS=ECDHE-RSA-AES128-SHA256 ECDHECURVES=P-384".
- .IP "tls_host_override [\fIhost\fP]"
- By default, TLS host verification uses the host name given by the \fBhost\fP command.
- This command allows one to use a different host name for verification. This is only
- useful in special cases.
- .IP "tls_min_dh_prime_bits [\fIbits\fP]"
- Deprecated, use \fBtls_priorities\fP instead.
- Set or unset the minimum number of Diffie-Hellman (DH) prime bits accepted for
- TLS sessions. The default is set by the TLS library and can be selected by
- using an empty argument to this command. Only lower the default (for example to
- 512 bits) if there is no other way to make TLS work with the remote server.
- .IP "from \fIenvelope_from\fP"
- Set the envelope-from address. The following substitution patterns are supported:
- .br
- %U will be replaced by $USER, or if that fails by $LOGNAME, or if that fails by
- the login name of the user running msmtp.
- .br
- %H will be replaced by $HOSTNAME, or if that fails by the host name of the system.
- .br
- %C will be replaced by the canonical name of %H.
- .br
- %M will be replaced by the contents of /etc/mailname (potentially a different
- directory is used depending on the build configuration; see the output of msmtp
- \-\-version and look for the location of the system configuration file).
- .br
- Note that the obsolete \fBauto_from\fP command replaces this envelope-from address.
- .br
- To enforce the use of this envelope-from address and ignore the \-f / \-\-from option,
- see the \fBallow_from_override\fP command.
- .br
- Furthermore, the envelope-from address may be a wildcard pattern as used for file name matching
- in the shell. This is the case if it contains one of the characters ?, * or [.
- This allows a variety of envelope-from addresses given with the \fI\-\-from\fP option to match a single account.
- .IP "allow_from_override (\fIon\fP|\fIoff\fP)
- By default, the \fI\-\-from\fP option overrides the \fBfrom\fP command.
- Set to \fIoff\fP to disable this.
- .IP "dsn_notify (\fIoff\fP|\fIcondition\fP)"
- This command sets the condition(s) under which the mail system should send DSN
- (Delivery Status Notification) messages. The argument \fIoff\fP disables
- explicit DSN requests, which means the mail system decides when to send DSN
- messages. This is the default.
- The \fIcondition\fP must be \fInever\fP, to never request notification, or a
- comma separated list (no spaces!) of one or more of the following:
- \fIfailure\fP, to request notification on transmission failure, \fIdelay\fP, to
- be notified of message delays, \fIsuccess\fP, to be notified of successful
- transmission. The SMTP server must support the DSN extension.
- .IP "dsn_return (\fIoff\fP|\fIamount\fP)"
- This command controls how much of a mail should be returned in DSN (Delivery
- Status Notification) messages. The argument \fIoff\fP disables explicit DSN
- requests, which means the mail system decides how much of a mail it returns in
- DSN messages. This is the default.
- The \fIamount\fP must be \fIheaders\fP, to just return the message headers, or
- \fIfull\fP, to return the full mail. The SMTP server must support the DSN
- extension.
- .IP "set_from_header [(\fIauto\fP|\fIon\fP|\fIoff\fP)]"
- When to set a From header: \fIauto\fP adds a From header if the mail does not
- have one (this is the default), \fIon\fP always sets a From header and overrides
- any existing one, and \fIoff\fP never sets a From header.
- .br
- If the mail server rejects the mail because its From header does not match the
- envelope-from address (a common anti-spam measure), then you might want to set
- this option to \fIon\fP.
- .br
- The From header is created based on the envelope-from address. Disable
- \fBallow_from_override\fP to prevent programs from setting their own
- envelope-from address.
- .br
- For compatibility with older versions, \fBadd_missing_from_header\fP [(\fIon\fP|\fIoff\fP)]
- is still supported and corresponds to the \fIauto\fP and \fIoff\fP settings.
- .IP "set_date_header [(\fIauto\fP|\fIoff\fP)]"
- When to set a Date header: \fIauto\fP adds a Date header if the mail does not
- have one (this is the default), and \fIoff\fP never sets a Date header.
- .br
- For compatibility with older versions, \fBadd_missing_date_header\fP [(\fIon\fP|\fIoff\fP)]
- is still supported and corresponds to the \fIauto\fP and \fIoff\fP settings.
- .IP "set_msgid_header [(\fIauto\fP|\fIoff\fP)]"
- When to set a Message-ID header: \fIauto\fP adds a Message-ID header if the mail does not
- have one (this is the default), and \fIoff\fP never sets a Message-ID header.
- .IP "remove_bcc_headers [(\fIon\fP|\fIoff\fP)]"
- This command controls whether to remove Bcc headers. The default is to remove them.
- .IP "undisclosed_recipients [(\fIon\fP|\fIoff\fP)]"
- When set, the original To, Cc, and Bcc headers of the mail are removed and a single
- new header line "To: undisclosed-recipients:;" is added. The default setting is off.
- .IP "logfile [\fIfile\fP]"
- An empty argument disables logging (this is the default).
- .br
- When logging is enabled by choosing a log file, msmtp will append one line to
- the log file for each mail it tries to send via the account that this log file
- was chosen for.
- .br
- The line will include the following information: date and time in the format
- specified by \fBlogfile_time_format\fP, host name of the
- SMTP server, whether TLS was used, whether authentication was used,
- authentication user name (only if authentication is used), envelope-from
- address, recipient addresses, size of the mail as transferred to the server
- (only if the delivery succeeded), SMTP status code and SMTP error message (only
- in case of failure and only if available), error message (only in case of
- failure and only if available), exit code (from sysexits.h; EX_OK indicates
- success).
- .br
- If the filename is a dash (\-), msmtp prints the log line to the standard
- output.
- .IP "logfile_time_format [\fIfmt\fP]"
- Set or unset the log file time format. This will be used as the format string
- for the strftime() function. An empty argument chooses the default
- ("%b %d %H:%M:%S").
- .IP "syslog [(\fIon\fP|\fIoff\fP|\fIfacility\fP)]"
- Enable or disable syslog logging. The facility can be one of LOG_USER, LOG_MAIL,
- LOG_LOCAL0, ..., LOG_LOCAL7. The default is LOG_USER.
- .br
- Each time msmtp tries to send a mail via the account that contains this syslog
- command, it will log one entry to the syslog service with the chosen facility.
- .br
- The line will include the following information: host name of the SMTP server,
- whether TLS was used, whether authentication was used, envelope-from address,
- recipient addresses, size of the mail as transferred to the server (only if the
- delivery succeeded), SMTP status code and SMTP error message (only in case of
- failure and only if available), error message (only in case of failure and only
- if available), exit code (from sysexits.h; EX_OK indicates success).
- .br
- .IP "aliases [\fIfile\fP]"
- Replace local recipients with addresses in the aliases file. The aliases file
- is a cleartext file containing mappings between a local address and a list of
- replacement addresses. The mappings are of the form:
- .br
- local: someone@example.com, person@domain.example
- .br
- Multiple replacement addresses are separated with commas. Comments start with `#'
- and continue to the end of the line.
- .br
- The local address \fIdefault\fP has special significance and is matched if the
- local address is not found in the aliases file. If no \fIdefault\fP alias is
- found, then the local address is left as is.
- .br
- An empty argument to the aliases command disables the replacement of local
- addresses. This is the default.
- .IP "auto_from [(\fIon\fP|\fIoff\fP)]
- Obsolete; you can achieve the same and more using the substitution patterns of the
- \fIfrom\fP command.
- .br
- Enable or disable automatic envelope-from addresses. The default is off.
- When enabled, an envelope-from address of the form user@domain will be
- generated. The local part will be set to \fBUSER\fP or, if that fails, to
- \fBLOGNAME\fP or, if that fails, to the login name of the current user. The
- domain part can be set with the \fBmaildomain\fP command. If the maildomain
- is empty, the envelope-from address will only consist of the user name and not
- have a domain part. When auto_from is disabled, the envelope-from address must
- be set explicitly.
- .IP "maildomain [\fIdomain\fP]"
- Obsolete; you can achieve the same and more using the substitution patterns of the
- \fIfrom\fP command.
- .br
- Set a domain part for the generation of an envelope-from address. This is only
- used when \fIauto_from\fP is on. The domain may be empty.
- .br
- .SH EXAMPLES
- .br
- .B Configuration file
- .PP
- .br
- # Example for a user configuration file ~/.msmtprc
- .br
- #
- .br
- # This file focusses on TLS and authentication. Features not used here include
- .br
- # logging, timeouts, SOCKS proxies, TLS parameters, Delivery Status Notification
- .br
- # (DSN) settings, and more.
- .br
- .br
- # Set default values for all following accounts.
- .br
- defaults
- .br
- .br
- # Use the mail submission port 587 instead of the SMTP port 25.
- .br
- port 587
- .br
- .br
- # Always use TLS.
- .br
- tls on
- .br
- .br
- # Set a list of trusted CAs for TLS. The default is to use system settings, but
- .br
- # you can select your own file.
- .br
- #tls_trust_file /etc/ssl/certs/ca\-certificates.crt
- .br
- .br
- # A freemail service
- .br
- account freemail
- .br
- .br
- # Host name of the SMTP server
- .br
- host smtp.freemail.example
- .br
- .br
- # As an alternative to tls_trust_file, you can use tls_fingerprint
- .br
- # to pin a single certificate. You have to update the fingerprint when the
- .br
- # server certificate changes, but an attacker cannot trick you into accepting
- .br
- # a fraudulent certificate. Get the fingerprint with
- .br
- # $ msmtp \-\-serverinfo \-\-tls \-\-tls\-certcheck=off \-\-host=smtp.freemail.example
- .br
- #tls_fingerprint 00\::11\::22\::33\::44\::55\::66\::77\::88\::99\::AA\::BB\::CC\::DD\::EE\::FF\::00\::11\::22\::33
- .br
- .br
- # Envelope-from address
- .br
- from joe_smith@freemail.example
- .br
- .br
- # Authentication. The password is given using one of five methods, see below.
- .br
- auth on
- .br
- user joe.smith
- .br
- .br
- # Password method 1: Add the password to the system keyring, and let msmtp get
- .br
- # it automatically. To set the keyring password using Gnome's libsecret:
- .br
- # $ secret\-tool store \-\-label=msmtp \\
- .br
- # host smtp.freemail.example \\
- .br
- # service smtp \\
- .br
- # user joe.smith
- .br
- .br
- # Password method 2: Store the password in an encrypted file, and tell msmtp
- .br
- # which command to use to decrypt it. This is usually used with GnuPG, as in
- .br
- # this example. Usually gpg\-agent will ask once for the decryption password.
- .br
- passwordeval gpg2 \-\-no\-tty \-q \-d ~/.msmtp\-password.gpg
- .br
- .br
- # Password method 3: Store the password directly in this file. Usually it is not
- .br
- # a good idea to store passwords in cleartext files. If you do it anyway, at
- .br
- # least make sure that this file can only be read by yourself.
- .br
- #password secret123
- .br
- .br
- # Password method 4: Store the password in ~/.netrc. This method is probably not
- .br
- # relevant anymore.
- .br
- .br
- # Password method 5: Do not specify a password. Msmtp will then prompt you for
- .br
- # it. This means you need to be able to type into a terminal when msmtp runs.
- .br
- .br
- # A second mail address at the same freemail service
- .br
- account freemail2 : freemail
- .br
- from joey@freemail.example
- .br
- .br
- # The SMTP server of your ISP
- .br
- account isp
- .br
- host mail.isp.example
- .br
- from smithjoe@isp.example
- .br
- auth on
- .br
- user 12345
- .br
- .br
- # Set a default account
- .br
- account default : freemail
- .br
- .PP
- .B Using msmtp with Mutt
- .PP
- Create a configuration file for msmtp and add the following lines to your
- Mutt configuration file:
- .br
- .B set sendmail="/path/to/msmtp"
- .br
- .B set use_from=yes
- .br
- .B set realname="Your Name"
- .br
- .B set from=you@example.com
- .br
- .B set envelope_from=yes
- .br
- The envelope_from=yes option lets Mutt use the
- .BR \-f
- option of msmtp. Therefore msmtp chooses the first account that matches
- the from address you@example.com.
- .br
- Alternatively, you can use the
- .BR \-a
- option:
- .br
- .B set sendmail="/path/to/msmtp \-a my\-account"
- .br
- Or set everything from the command line (but note that you cannot set a password
- this way):
- .br
- .B set sendmail="/path/to/msmtp \-\-host=mailhub \-f me@example.com \-\-tls
- .B \-\-tls\-trust\-file=trust.crt"
- .PP
- If you have multiple mail accounts in your msmtp configuration file
- and let Mutt use the
- .BR \-f
- option to choose the right one, you can easily switch accounts in Mutt with
- the following Mutt configuration lines:
- .br
- .B macro generic\ "<esc>1"\ ":set from=you@example.com"
- .br
- .B macro generic\ "<esc>2"\ ":set from=you@your\-employer.example"
- .br
- .B macro generic\ "<esc>3"\ ":set from=you@some\-other\-provider.example"
- .PP
- .B Using msmtp with mail
- .PP
- Define a default account, and put the following in your ~/.mailrc:
- .br
- .B set sendmail="/path/to/msmtp"
- .PP
- .B Using msmtp with Tor
- .PP
- Use the following settings:
- .br
- .B proxy_host 127.0.0.1
- .br
- .B proxy_port 9050
- .br
- .B tls on
- .br
- Use an IP address as proxy host name, so that msmtp does not leak a DNS query
- when resolving it.
- .br
- TLS is required to prevent exit hosts from reading your SMTP session.
- .br
- Do not set \fBdomain\fP to something that you do not want to reveal (do not set
- it at all if possible).
- .PP
- .B Aliases file
- .PP
- # Example aliases file
- # Send root to Joe and Jane
- .br
- root: joe_smith@example.com, jane_chang@example.com
- # Send cron to Mark
- .br
- cron: mark_jones@example.com
- # Send everything else to admin
- .br
- default: admin@domain.example
- .SH FILES
- .IP "SYSCONFDIR/msmtprc"
- System configuration file. Use
- .B \-\-version
- to find out what SYSCONFDIR is on your platform.
- .IP "~/.msmtprc or $XDG_CONFIG_HOME/msmtp/config"
- User configuration file.
- .IP "~/.netrc and SYSCONFDIR/netrc"
- The netrc file contains login information. Before prompting for a password,
- msmtp will search it in ~/.netrc and SYSCONFDIR/netrc.
- .SH ENVIRONMENT
- .IP "USER, LOGNAME"
- These variables override the user's login name when constructing an
- envelope-from address. LOGNAME is only used if USER is unset.
- .IP "TMPDIR"
- Directory to create temporary files in. If this is unset, a system specific
- default directory is used.
- .br
- A temporary file is only created when the
- .BR \-t/\-\-read\-recipients
- or
- .BR \-\-read\-envelope\-from
- option is used. The file is then used to buffer the headers of the mail (but not
- the body, so the file won't get very large).
- .IP "EMAIL, SMTPSERVER"
- These environment variables are used only if neither \fB\-\-host\fP nor
- \fB\-\-account\fP is used and there is no default account defined in the
- configuration files. In this case, the host name is taken from SMTPSERVER, and
- the envelope from address is taken from EMAIL, unless overridden by
- \fB\-\-from\fP or \fB\-\-read\-envelope\-from\fP. Currently SMTPSERVER must
- contain a plain host name (no URL), and EMAIL must contain a plain address (no
- names or additional information).
- .SH AUTHORS
- msmtp was written by Martin Lambers <marlam@marlam.de>.
- .br
- Other authors are listed in the AUTHORS file in the source distribution.
- .SH SEE ALSO
- .BR sendmail (8),
- .BR netrc (5)
- or
- .BR ftp (1)